Create a Stateful or Stateless Service
This section describes how to create a stateful or stateless service.
Prerequisites
You need to join a project and have the Application Workload Management permission in the project. For more information, see Project Members and Project Roles.
Steps
Refer to Parameter Description to set the service parameters.
-
Log in to the KubeSphere web console with a user who has Application Workload Management permissions and enter your workspace.
-
Click Application Workloads > Services in the left navigation pane.
-
Select a project from the drop-down list in the upper left corner of the page.
-
Click Create on the page.
-
In the Create Service dialog box, select Stateful Service or Stateless Service as needed.
Note -
Stateful Service: The service’s internal access mode is Headless, and the backend workload is a StatefulSet.
-
Stateless Service: The service’s internal access mode is VirtualIP, and the backend workload is a Deployment.
-
-
On the Basic Information tab, configure the basic information for the service, then click Next.
-
On the Pod Settings tab, configure the replica count, containers, update strategy, security context, scheduling rules, and metadata for the pods managed by the service’s backend workload, then click Next.
-
On the Storage Settings tab, mount volumes for the containers managed by the service backend workload, then click Next.
-
On the Advanced Settings tab, specify nodes for the pods managed by the service backend workload, configure the service’s external access mode, session affinity settings, and metadata, then click Create. After creation, the service will be displayed in the service list.
Parameter Description
The following describes how to set parameters for stateful and stateless services.
-
Basic Information
Set the basic information of the service.
Parameter Description Name
The name of the service. Service names must be unique within a project. The name can only contain lowercase letters, numbers, and hyphens (-), must start with a lowercase letter, and must end with a lowercase letter or a number. The maximum length is 63 characters.
Alias
The alias of the service. Different services can have the same alias.
Version
The version number of the service. The version can only contain lowercase letters and numbers, with a maximum length of 16 characters.
Description
The description of the service. The description can contain any characters, with a maximum length of 256 characters.
-
Pod Settings > Pod Replicas
Click
/
to increase/decrease the number of pod replicas. The minimum value is 1. -
Pod Settings > Add Container
Create containers to run in the pod. You can create multiple containers in a pod.
-
Click Add Container to create a container.
-
Hover over a created container, then click
on the right to edit the container’s settings. -
Hover over a created container, then click
on the right to delete the container.
-
-
Pod Settings > Add Container > Container Settings
Set the image, name, type, and resources for the container.
Parameter Description Image
The image required to create the container.
-
Enter the name (e.g., nginx:latest) or path (e.g., docker.io/nginx:latest) of the image, then press Enter to search for the image.
-
If you only enter the image name, it will be pulled from Docker Hub by default. To use a private image service, you need to create a Secret containing the private image service information, then select the private image service from the left side of the Image text box.
-
Click
to browse images in the current image service.
Container Name
The name of the container. The name can only contain lowercase letters, numbers, and hyphens (-), must start and end with a lowercase letter or number, and can be up to 63 characters long.
Container Type
The type of container.
-
Init Container: A container that performs initialization work for the main application container. The main application container will only start after all init containers have completed successfully. If an init container fails, the system will set the pod’s status to failed.
-
Main Container: The container that runs the application. It is generally recommended to run only one main container per pod.
CPU Reservation
CPU resources reserved for the container, in cores.
CPU Limit
The maximum CPU resources allowed for the container, in cores.
Memory Reservation
Memory resources reserved for the container, in MiB.
Memory Limit
The maximum memory resources allowed for the container, in MiB.
GPU Type
The type of GPU allowed for the container.
GPU Limit
The maximum number of GPUs allowed for the container, in GPUs.
-
-
Pod Settings > Add Container > Port Settings
Set the container port. Click Use Default Image Port to set the container port to the default port of the image. Click Add Port to set multiple ports for the container.
Parameter Description Protocol
The actual protocol that the application in the container listens on. To use the application governance features provided by KubeSphere, ensure that the protocol selected here is consistent with the actual protocol that the application in the container listens on.
Name
The name of the port. To use the application governance features provided by KubeSphere, use the lowercase protocol name as the prefix of the port name (e.g., http-).
Container Port
The actual port number that the application in the container listens on.
-
Pod Settings > Add Container > Image Pull Policy
Configure whether to pull images from the image service when creating or updating a pod.
Parameter Description Prefer Local Image
When creating or updating a pod, prioritize using the image files stored on the node by the container runtime.
Always Pull Image
When creating or updating a pod, always attempt to pull the image from the image service.
Use Local Image Only
When creating or updating a pod, use only the images stored on the node by the container runtime. If the required image does not exist locally, pod creation will fail.
-
Pod Settings > Add Container > Health Check
Check the health status of containers. Before using this feature, you need to configure your container’s application to return health check results.
KubeSphere supports the following health check types:
Parameter Description Liveness Probe
Checks if the container is alive. If the liveness probe fails, the system will attempt to restart the container.
Readiness Probe
Checks if the container is ready. If the readiness probe fails, the system will prevent access to the pod where the container resides via services.
Startup Probe
Checks if the container has started. If the startup probe fails, the system will disable other probes for the container and attempt to restart the container.
KubeSphere supports the following check methods:
Parameter Description HTTP Request
Sends an HTTP GET request to the pod’s virtual IP address. The check is successful if the response status code is 2XX or 3XX.
Command
Runs a command inside the container. The check is successful if the command’s exit code is 0.
TCP Port
Attempts to establish a TCP connection to the specified container port. The check is successful if the connection is established.
-
Pod Settings > Add Container > Health Check > Add Probe
Create probes to perform liveness, readiness, or startup checks on containers.
-
Click Add Probe to create a probe.
-
Hover over a created probe, then click
on the right to edit the probe’s settings. -
Hover over a created probe, then click
on the right to delete the probe.
Parameter Description Path
The protocol (HTTP or HTTPS) for the HTTP request, the path of the request target relative to the pod’s virtual IP address, and the port number for the request. Available only when the health check method is HTTP Request.
Command
The command to be executed inside the container. You can use commas (,) to separate the command and its arguments. Available only when the health check method is Command.
Port
The container port number for TCP checks. Available only when the health check method is TCP Port.
Initial Delay
The delay time, in seconds, after the container starts before the probe is initiated.
Timeout
The probe timeout period, in seconds. After the probe times out, the check is considered a failure. The value must be an integer, with a minimum value of 0.
Check Interval
The time interval, in seconds, between check executions. The value must be an integer, with a minimum value of 1.
Success Threshold
The minimum number of consecutive successful checks required after a failure for the check to be considered successful again. The minimum value is 1. For liveness and startup probes, this value must be 1.
Failure Threshold
The minimum number of consecutive failed checks required after a success for the check to be considered failed again. The minimum value is 1.
-
-
Pod Settings > Add Container > Lifecycle Management
Set the actions that need to be executed after a container starts or before it terminates, for environment checks or graceful termination. Before using this feature, you need to configure your container’s application so that it can return the execution result of the action.
Parameter Description Post-start Action
The action to be executed after the container starts. If this action fails, the system will attempt to restart the container.
Pre-stop Action
The action to be executed before the container terminates. This action follows these rules:
-
If the pre-stop action fails, the system will terminate the container immediately.
-
The default value for the container’s graceful termination period is 30s. If the pre-stop action is still executing when the graceful termination period is reached, the system will provide a one-time grace period of 2s.
-
After the grace period ends, regardless of whether the pre-stop action has finished executing, the system will terminate the container.
KubeSphere supports the following execution methods for post-start and pre-stop actions:
Parameter Description HTTP Request
Send an HTTP GET request to the pod’s virtual IP address. If the response status code is 2XX or 3XX, the action is considered successful.
Command
Run a command inside the container. If the command’s exit code is 0, the action is considered successful.
TCP Port
Attempt to establish a TCP connection to the specified container port. If the connection is successfully established, the action is considered successful.
-
-
Pod Settings > Add Container > Lifecycle Management > Add Action
Create post-start or pre-stop actions for containers.
-
Click Add Action to create an action.
-
Hover over a created action, then click
on the right to edit the action’s settings. -
Hover over a created action, then click
on the right to delete the action.
Parameter Description Path
The protocol (HTTP or HTTPS), the path of the request target relative to the pod’s virtual IP address, and the port number for the HTTP request. Available only when the action execution method is HTTP Request.
Command
The command to be run inside the container. You can use commas (,) to separate the command and its arguments. Available only when the action execution method is Command.
Port
The container port number for TCP checks. Available only when the action execution method is TCP Port.
-
-
Pod Settings > Add Container > Startup Command
Set the command to be executed inside the container when it starts.
Parameter Description Command
The name of the command to be executed.
Arguments
The arguments for the command to be executed. You can use commas (,) to separate multiple arguments.
-
Pod Settings > Add Container > Environment Variables
Set environment variables for the container.
-
Click Add Environment Variable to set multiple environment variables.
-
Click Batch Reference to create environment variables using data from a ConfigMap or Secret. The ConfigMap or Secret must belong to the same project as the container to be referenced by the container. After the container is created, the values of the environment variables will not change dynamically with updates to the ConfigMap or Secret settings.
-
Click
on the right side of a created environment variable to delete it.
Parameter Description Key
The name of the environment variable.
Value
The value of the environment variable.
Resource
The name of the ConfigMap or Secret. Only available when referencing a ConfigMap or Secret.
Key in Resource
The key within the ConfigMap or Secret. The value corresponding to this key will be used as the value of the environment variable. Only available when referencing a ConfigMap or Secret.
-
-
Pod Settings > Add Container > Container Security Context
Set the permissions of container processes in the Linux system.
Parameter Description Access Control
Access permissions for container processes.
-
Privileged Mode: Runs the container process as the root user on the host.
-
Allow Privilege Escalation: Allows the container process to acquire more privileges than its parent process. This option is enabled by default when Privileged Mode is enabled.
-
Read-only Root Filesystem: Sets the root directory of the container’s filesystem to read-only.
Users and User Groups
The user and user group that run the container process entry point.
-
Run as non-root only: Check whether the container will run as the root user before starting the container. If the container will run as the root user, the container will not be started. When this feature is enabled, the system will ignore the Privileged Mode setting.
-
User: The UID that executes the container process entry point. Defaults to the UID specified in the image metadata.
-
User Group: The GID that executes the container process entry point. Defaults to the default GID of the container runtime.
SELinux Context
The SELinux label for the container process, including Level, Role, Type, and User. For more information, refer to the SELinux official documentation.
Capabilities
Additional permissions added to or removed from container processes in the Linux system. Refer to the Linux official documentation for a list of Linux process capabilities.
-
When adding or removing capabilities for container processes, you need to remove the CAP_ prefix from the capability name. For example, entering SYS_TIME in the Remove text box removes the CAP_SYS_TIME capability from the container process.
-
Click Add to set multiple capability addition or removal instructions.
-
-
Pod Settings > Add Container > Sync Host Timezone
Selecting the checkbox to the left of Synchronize Host Timezone will synchronize the timezone of the container with that of the host.
-
Pod Settings > Update Strategy
Set the strategy for pod updates during deployment.
Deployment:
Parameter Description Rolling Update (Recommended)
Gradually replaces old pod replicas with new ones. During the upgrade, traffic is load-balanced between old and new pod replicas, ensuring no service interruption. If you choose this strategy, you need to further configure the Maximum Unavailable Pods and Maximum Surge Pods.
Recreate
Deletes all old pod replicas before creating new ones. Service will be interrupted during the upgrade.
StatefulSet:
Parameter Description Rolling Update (Recommended)
Gradually replaces old pod replicas with new ones. During the upgrade, traffic is load-balanced between old and new pod replicas, ensuring no service interruption. If you choose this strategy, you need to further configure the Partition.
On Delete
Pods must be manually deleted before they can be updated.
DaemonSet:
Parameter Description Rolling Update (Recommended)
Gradually replaces old pod replicas with new ones. During the upgrade, traffic is load-balanced between old and new pod replicas, ensuring no service interruption. If you choose this strategy, you need to further configure the Max Unavailable and Min Ready Seconds.
On Delete
Pods must be manually deleted before they can be updated.
-
Pod Settings > Update Strategy > Rolling Update Settings
Set the relevant parameters for the rolling update strategy.
Deployment:
Parameter Description Max Unavailable Pods
The maximum number or percentage of unavailable pod replicas allowed during the update process.
Max Surge Pods
The maximum number or percentage of extra pod replicas allowed during the update process.
StatefulSet:
Parameter Description Pod Management Policy
Set a partition number to divide the pod replicas into two groups. When updating the StatefulSet, only pod replicas with an ordinal number greater than or equal to the partition number will be updated.
DaemonSet:
Parameter Description Max Unavailable Pods
The maximum number or percentage of unavailable pod replicas allowed during the update process.
Min Ready Seconds
The minimum stable running duration required for a pod replica to be considered ready.
-
Pod Settings > Pod Security Context
Set the permissions of all container processes in the pod within the Linux system. If both the pod security context and the container security context have set the user, user group, and SELinux context, the settings in the container security context will override those in the pod security context.
Parameter Description Users and User Groups
The user and user group that run the container process entry point.
-
Run as non-root only: Check whether the container will run as the root user before starting the container. If the container will run as the root user, the container will not be started. When this feature is enabled, the system will ignore the Privileged Mode setting.
-
User: The UID that executes the container process entry point. Defaults to the UID specified in the image metadata.
-
User Group: The GID that executes the container process entry point. Defaults to the default GID of the container runtime.
SELinux Context
The SELinux label for the container process, including Level, Role, Type, and User. For more information, refer to the SELinux official documentation.
-
-
Pod Settings > Pod Scheduling Rules
Set rules for scheduling pod replicas to nodes.
Parameter Description Default Rule
Do not specify a particular rule; let the system decide which node to schedule the pod replicas to.
Scatter Scheduling
Try to schedule pod replicas to different nodes as much as possible.
Concentrate Scheduling
Try to schedule pod replicas to the same node as much as possible.
Custom Rule
Schedule pod replicas to nodes according to user-defined rules. If you select this option, you need to further customize the scheduling rules.
-
Pod Settings > Pod Scheduling Rules > Custom Rules
Set custom pod scheduling rules.
-
Click Add to set multiple rules.
-
Click
on the right side of a created rule to delete it.
Parameter Description Type
The type of the rule.
-
Schedule with Target: Pod replicas will be scheduled onto the same node as pods with specific labels in the current project.
-
Away from Target: Pod replicas will be scheduled onto different nodes from pods with specific labels in the current project.
Strategy
The enforcement strategy of the rule.
-
Prefer Matching: Try to meet the rule requirements as much as possible. If the rule requirements cannot be met, pod replicas will be scheduled onto nodes that do not meet the requirements.
-
Must Match: The rule requirements must be met. If the rule requirements cannot be met, pod replicas cannot be scheduled onto any node.
Target
The target of the rule. Pod replicas will be scheduled onto the same node or different nodes as pods with the app=<target> label (<target> is the value selected here), depending on the rule’s type and strategy.
-
-
Pod Settings > Pod Graceful Termination
Set the waiting time before container termination. The container will be forcibly terminated after the timeout. The default value is 30s.
-
Pod Settings > Add Metadata
Set the metadata of the pod. Currently, only setting annotations for the pod is supported; setting labels for the pod is not supported.
-
Click Add to set multiple annotations.
-
Click
on the right side of a created annotation to delete it.
-
-
Storage Settings
Mount volumes, ConfigMaps or Secrets for containers.
Parameter Description Add Persistent Volume Claim Template
Add a Persistent Volume Claim template for a StatefulSet. The system will create a separate Persistent Volume Claim and Persistent Volume for each pod replica and mount the Persistent Volumes to the specified container in each pod replica. Only available for StatefulSets.
Mount Volume
Mount persistent volumes, ephemeral volumes, or HostPath volumes to containers.
Mount ConfigMap or Secret
Mount data from a ConfigMap or Secret as a volume to a container.
-
Hover over an added volume or PersistentVolumeClaim template, then click
on the right to edit the settings of the volume or PersistentVolumeClaim template. -
Hover over a mounted volume or PersistentVolumeClaim template, then click
on the right to delete the volume or PersistentVolumeClaim template.
-
-
Storage Settings > Add PersistentVolumeClaim Template
Provision PersistentVolumeClaim and PersistentVolume individually for each pod replica using persistent volume claim templates, and mount the persistent volume to the container. Only available for StatefulSets.
Parameter Description PVC Name Prefix
The name prefix for the PersistentVolumeClaims created via the persistent volume claim template. The system will automatically name the PersistentVolumeClaim in the format <Name Prefix>-<Workload Name>-<Sequence Number>. The PersistentVolumeClaims for different pod replicas of the same StatefulSet are distinguished by the <Sequence Number>.
Storage Class
The storage class used to create the PersistentVolumeClaim.
Access Mode
Read and Write Modes for Persistent Volumes.
-
RWO (ReadWriteOnce): Allows a single node to read data from and write data to the persistent volume.
-
ROX (ReadOnlyMany): Allows multiple nodes to read data from the persistent volume.
-
RWX (ReadWriteMany): Allows multiple nodes to read data from and write data to the persistent volume.
Volume Capacity
The capacity of each persistent volume created via the persistent volume claim template.
Mount Mode
The method by which a volume is mounted to a container.
-
ReadWrite: Allows the container to read data from and write data to the volume.
-
ReadOnly: Only allows the container to read data from the volume.
-
Unmounted: The volume is not mounted to the container.
Mount Path
The path where the volume is mounted to the container. Click
to set the subpath of the volume to be mounted. If no subpath is set, the entire volume is mounted by default. -
-
Storage Settings > Mount Volume > Persistent Volume
Mount a persistent volume for a container. The persistent volume claim used to create the persistent volume must belong to the same project as the container.
Parameter Description Select Persistent Volume Claim
Select the persistent volume claim used to create the persistent volume. This persistent volume claim must belong to the same project as the container. If there are no available persistent volume claims in the container’s project, you need to create one in advance.
Mount Mode
The method by which a volume is mounted to a container.
-
ReadWrite: Allows the container to read data from and write data to the volume.
-
ReadOnly: Only allows the container to read data from the volume.
-
Unmounted: The volume is not mounted to the container.
Mount Path
The path where the volume is mounted to the container. Click
to set the subpath of the volume to be mounted. If no subpath is set, the entire volume is mounted by default. -
-
Storage Settings > Mount Volume > Temporary Volume
Mount a temporary volume for a container. Temporary volumes have the following characteristics:
-
Automatically created by the system in the storage system of the node where the pod resides.
-
Automatically managed by the system, with a capacity limit equal to the node’s storage capacity.
-
Cannot store persistent data. The temporary volume is automatically created by the system when the pod is created and automatically deleted when the pod is deleted.
Parameter Description Volume Name
The name of the temporary volume.
Capacity Limit
The capacity limit of the current volume.
Mount Mode
The method by which a volume is mounted to a container.
-
ReadWrite: Allows the container to read data from and write data to the volume.
-
ReadOnly: Only allows the container to read data from the volume.
-
Unmounted: The volume is not mounted to the container.
Mount Path
The path where the volume is mounted to the container. Click
to set the subpath of the volume to be mounted. If no subpath is set, the entire volume is mounted by default. -
-
Storage Settings > Mount Volume > HostPath Volume
Mount files or directories from the node where the pod is located to the container.
-
Files or folders at the same path on different nodes may differ, so pod replicas on different nodes may read different data from the HostPath volume.
-
You need to ensure that the mounted path exists on the node where the pod is located and that the pod process has the necessary permissions. Otherwise, the pod process will be unable to read data from or write data to the HostPath volume.
Parameter Description Volume Name
The name of the HostPath volume.
Host Path
The path of the file or folder on the node that needs to be mounted.
Mount Mode
The method by which a volume is mounted to a container.
-
ReadWrite: Allows the container to read data from and write data to the volume.
-
ReadOnly: Only allows the container to read data from the volume.
-
Unmounted: The volume is not mounted to the container.
Mount Path
The path where the volume is mounted to the container. Click
to set the subpath of the volume to be mounted. If no subpath is set, the entire volume is mounted by default. -
-
Storage Settings > Mount ConfigMap or Secret
Mount data from a ConfigMap or Secret as a volume to a container.
Parameter Description Select ConfigMap/Select Secret
Select a ConfigMap or Secret from the current project.
Mount Mode
Set how the data from the ConfigMap or Secret is mounted on the container. ConfigMaps and Secrets only support mounting as Read-Only or Do Not Mount.
Mount Path
Set the path on the container where the data from the ConfigMap or Secret is mounted.
-
The system will generate a folder based on the data in the ConfigMap or Secret, mapping each key-value pair to a file, where the key is the filename and the value is the file content.
-
Click
to specify key-value pairs from the ConfigMap or Secret to be mounted as files. If no subpath is specified, the entire ConfigMap or Secret is mounted by default. If a subpath is used, the files mounted into the container will not be dynamically updated with changes to the ConfigMap or Secret.
Select Specific Key
Mount key-value pairs from the ConfigMap or Secret as files into the container. Files mounted into the container will be dynamically updated with changes to the ConfigMap or Secret. Click Add to mount multiple key-value pairs.
-
Key: The key name of the key-value pair in the ConfigMap or Secret that needs to be mounted.
-
Path: The path within the container relative to the Mount Path. The specified key-value pair from the ConfigMap or Secret will be mounted at this path, overwriting any existing files at the Mount Path.
-
-
Advanced Settings
Specify nodes for the pods managed by the service backend workload, and configure the service’s external access mode, session persistence settings, and metadata.
Parameter Description External Access
The external access mode for the service.
-
NodePort: The system maps a node’s port to the service port, allowing access to the service via the node’s IP address and the node port.
-
LoadBalancer: The system allocates an external IP address for the service based on a NodePort service and binds the external IP address to an external load balancer. The external load balancer listens on the node port corresponding to the service, enabling access to the service via the external IP address. To achieve this functionality, a LoadBalancer type service requires support from a load balancer plugin and the underlying infrastructure environment, and relevant annotations need to be set. For more information, please contact your infrastructure environment provider.
Session Affinity
Configure the system to forward all requests from the same client within the same session to the same pod within a specified time period. The default maximum session affinity time is 10800 seconds, but you can also manually set the maximum session affinity time.
Select Node
Schedule pod replicas to nodes with specified labels.
-
You can manually enter the label key-value pairs for the target node, or click Specify Node to select a node.
-
Click Add Node Selector to set multiple labels. Pod replicas will be scheduled to nodes that have all the specified labels.
-
Click
to the right of a created label to delete it.
Add Metadata
Set labels for services and annotations for workloads.
-
Click Add to set multiple labels or annotations.
-
Click
on the right side of a created label or annotation to delete it.
-