Create a Stateful or Stateless Service
This section describes how to create a stateful or stateless service in a multi-cluster project.
Prerequisites
-
Application Management for Cluster Federation should have been installed and enabled.
-
You should join a multi-cluster project and have the Federated Project Management permission within the project.
Steps
Refer to Parameter Description to set the parameters for the service.
-
Log in to the KubeSphere web console with a user who has the Federated Project Management permission, and access your multi-cluster project.
-
Click Application Workloads > Services in the left navigation pane.
-
Click Create on the page.
-
In the Create Service dialog, select Stateful Service or Stateless Service as needed.
Note -
Stateful Service: The internal access mode of the service is Headless, and the backend workload is Statefulset.
-
Stateless Service: The internal access mode of the service is VirtualIP, and the backend workload is Deployment.
-
-
On the Basic Information tab, configure the basic information for the service, and then click Next.
-
On the Pod Settings tab, set the number of replicas, containers, update strategy, security context, scheduling rules, and metadata for the pods managed by the service backend workload in the cluster, 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 IP pools and nodes for the pods managed by the service backend workload, set the external access mode, session persistence settings, and metadata for the service, then click Next.
-
On the Cluster Differences tab, differentiate the services in different clusters based on containers, ports, and environment variables, then click Create. After the service is created, it will be displayed in the service list.
Parameter Description
The following describes how to set the parameters for stateful and stateless services.
-
Basic Information
Configure the basic information for the service.
Parameter Description Name
The name of the service. Service names within the same project must be unique. Names can only contain lowercase letters, numbers, and hyphens (-), and must start and end with a lowercase letter or number, with a maximum length of 253 characters.
Alias
The alias of the service. Aliases can be the same for different services. Aliases can only contain Chinese characters, letters, numbers, and hyphens (-), and must not start or end with a hyphen (-), with a maximum length is 63 characters.
Version
The version number of the service. Versions 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 > Number of Pod Replicas
Click
or 
to increase/decrease the number of pod replicas. The minimum value is 1. -
Pod Settings > Add Container
Create containers to run within the pod. You can create multiple containers within a pod.
-
Click Add Container to create a container.
-
Hover over a created container, then click
on the right to edit the container settings. -
Hover over a created container, then click
on the right to delete the container.
-
-
Pod Settings > Add Container > Container Settings
Configure the container’s image, name, type, and resources.
Parameter Description Image
The image required to create the container.
-
Enter the image name (e.g., nginx:latest) or path (e.g., docker.io/nginx:latest), then press Enter to search for the image.
-
If you only enter the image name, the image will be pulled from Docker Hub by default. To use a private image registry, you need to create a Secret containing the information for the private image registry, and then select the private image registry on the left side of the Image text box.
-
Click
to browse images in the current image registry.
Container Name
The name of the container. The name can only contain lowercase letters, numbers, and hyphens (-). It must start and end with a lowercase letter or number, with a maximum length of 63 characters.
Container Type
The type of container.
-
Init Container: A container that performs initialization tasks for the working containers. The working containers will only start after all init containers have successfully completed. If an init container fails, the system sets the status of the pod to failure.
-
Work Container: A container that runs the application. It is generally recommended to have only one work container running in each pod.
CPU Request
Reserved CPU resources for a container, measured in cores.
CPU Limit
Upper limit of CPU resources that a container is allowed to use, measured in cores.
Memory Request
Reserved memory resources for a container, measured in MiB.
Memory Limit
Upper limit of memory resources that a container is allowed to use, measured in MiB.
GPU Type
The GPU type that containers in the project can use. Currently, only NVIDIA GPU is supported.
GPU Limit
Upper limit on the number of GPUs that a container is allowed to use, measured in GPUs.
-
-
Pod Settings > Add Container > Port Settings
Configure the ports for the container. Click Use Default Port of Images to set the container ports to the default ports of the image. Click Add Port to set multiple ports for the container.
Parameter Description Protocol
The protocol that the application in the container actually listens to. To use the Application Governance features provided by KubeSphere, ensure that the selected protocol matches the protocol that the application in the container actually listens to.
Name
The name of the port. To use the Application Governance features provided by KubeSphere, use the lowercase protocol name as a prefix for the port name (e.g., http-).
Container Port
The port number that the application in the container actually listens to.
-
Pod Settings > Add Container > Image Pull Policy
Set whether to pull images from the image registry when creating or updating Pods.
Parameter Description Use Local Image First
When creating or updating a pod, prioritize using the images stored by the container runtime on the node.
Pull Image Always
When creating or updating a pod, pull the image from the image registry every time.
Use Local Image Only
When creating or updating a pod, only use the images stored by the container runtime on the node. If the required image is not available locally, the pod may be created with an exception.
-
Pod Settings > Add Container > Health Check
Check the health status of the container. Before using this feature, you need to configure the application within the container to return the results of the health check.
KubeSphere supports the following types of health check:
Parameter Description Liveness Check
Checks if the container is alive. If the liveness check fails, the system will attempt to restart the container.
Readiness Check
Checks if the container is ready to process requests. If the readiness check fails, the system will prevent access to the pod through a service.
Startup Check
Checks if the container has started. If the startup check fails, the system will disable other probes for the container and attempt to restart it.
KubeSphere supports the following check methods:
Parameter Description HTTP Request
Sends an HTTP GET request to the virtual IP address of the pod. If the response status code is 2XX or 3XX, the check is considered successful.
Command
Runs a command in the container. The check is considered successful if the command’s exit code is 0.
TCP Port
Attempts to establish a TCP connection with the specified container port. The check is considered successful if the connection is established.
-
Pod Settings > Add Container > Health Check > Add Probe
Create probes for liveness, readiness, or startup checks on the container.
-
Click Add Probe to create a probe.
-
Hover over the created probe, then click
on the right to edit the probe settings. -
Hover over the created probe, then click
on the right to delete the probe.
Parameter Description Path
The protocol (HTTP or HTTPS), the path relative to the virtual IP address of the pod for HTTP requests, and the port number for the request. Only available when the health check method is HTTP Request.
Command
The command to run in the container. You can use commas (,) to separate the commands and its parameters. Only available when the health check method is Command.
Port
The container port number for TCP checks. Only available when the health check method is TCP Port.
Initial Delay
The delay time in seconds before the probe is initiated after container startup.
Timeout
The timeout period for the probe in seconds. After the timeout, the check will be considered a failure. The value must be an integer, with a minimum of 0.
Check Interval
The time interval for performing checks in seconds. The value must be an integer, with a minimum of 1.
Success Threshold
The minimum consecutive successes required to consider the check successful after a failure. The minimum value is 1. For liveness probes and startup probes, this parameter must be 1.
Failure Threshold
The minimum consecutive failures required to consider the check failed after a success. The minimum value is 1.
-
-
Pod Settings > Add Container > Lifecycle Management
Configure actions to be performed after the container starts or before it terminates for environment checking or graceful termination. Before using this feature, you need to configure the application within the container to return the results of the performed action.
Parameter Description Post-start Action
The action to be performed after the container starts. If the post-start action fails, the system will attempt to restart the container.
Pre-stop Action
The action to be performed before the container terminates. This action follows these rules:
-
If the pre-stop action fails, the system will terminate the container immediately.
-
The default period for the graceful termination of a container is 30 seconds. If the pres-stop action is still running when the grace period ends, the system will provide a one-time grace period of 2 seconds.
-
After the grace period ends, regardless of whether the pres-stop action has finished, the system will terminate the container.
KubeSphere supports the following execution methods for post-start actions and pre-stop actions:
Parameter Description HTTP Request
Sends an HTTP GET request to the virtual IP address of the pod. If the response status code is 2XX or 3XX, the action is considered successful.
Command
Runs a command in the container. The action is considered successful if the command’s exit code is 0.
TCP Port
Attempts to establish a TCP connection with the specified container port. The action is considered successful if the connection is established.
-
-
Pod Settings > Add Container > Lifecycle Management > Add Action
Create post-start or pre-termination actions for the container.
-
Click Add Action to create an action.
-
Hover over the created action, then click
on the right to edit the action settings. -
Hover over the created action, then click
on the right to delete the action.
Parameter Description Path
The protocol (HTTP or HTTPS), the path relative to the virtual IP address of the pod for HTTP requests, and the port number for the request. Only available when the action execution method is HTTP Request.
Command
The command to run in the container. You can use commas (,) to separate the commands and its parameters. Only available when the action execution method is Command.
Port
The container port number for TCP checks. Only available when the action execution method is TCP Port.
-
-
Pod Settings > Add Container > Start Command
Configure the command to be executed inside the container when it starts.
Parameter Description Command
The startup command to be executed.
Parameters
The parameters of the startup command. Use commas to separate multiple parameters.
-
Pod Settings > Add Container > Environment Variables
Configure 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 to be referenced must belong to the same project as the container. The values of environment variables will not dynamically change with changes made in the ConfigMap or Secret after the container is created.
-
Click
on the right of the 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 in 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 > Pod Security Context
Configure the permissions of the container process in the Linux system.
Parameter Description Access Control
Access permissions for the container process.
-
Privileged Mode: Run the container process as the root user on the host.
-
Allow Privilege Escalation: Allow the container process to gain more privileges than the parent process. This option is enabled by default when Privileged Mode is enabled.
-
Root Directory Read-Only: Set the root directory of the container filesystem to read-only.
User and User Group
The users and user groups running the entry point of container processes.
-
Run as Non-root: Checks if the container will run as the root user before starting. If the container is set to run as the root user, it won’t start. When this feature is enabled, the system will ignore the Privileged mode setting.
-
User: The UID (User ID) executing the container process entry point. Defaults to the UID specified in the image metadata.
-
User Group: The GID (Group ID) executing the container process entry point. Defaults to the default GID of the container runtime.
SELinux Context
The SELinux labels for the container process, including Level, Role, Type, and User. For more information, refer to the SELinux Documentation.
Capabilities
Additional capabilities added to or removed from the container process in the Linux system. Refer to the Linux Documentation for the list of Linux process capabilities.
-
When adding or removing capabilities for the container process, you need to remove the CAP_ prefix from the capability names. For example, entering SYS_TIME in the Drop text box will remove the CAP_SYS_TIME capability from the container process.
-
Click Add to set multiple instructions for adding or removing capabilities.
-
-
Pod Settings > Add Container > Sync Host Timezone
Select the checkbox on the left of Synchronize Host Timezone will synchronize the timezone between the container and the host.
-
Pod Settings > Update Strategy
Set the update strategy for pods.
Parameter Description Rolling Update (Recommended)
Gradually replace old pod replicas with new ones. During the update, the business traffic is load-balanced between old and new pod replicas, ensuring uninterrupted service. If you choose this strategy, you need to further configure Maximum Unavailable Pods and Maximum Extra Pods.
Simultaneous Update
Delete all existing pod replicas and create new ones. The service is interrupted during the update.
-
Pod Settings > Update Strategy > Rolling Update Settings
Configure the parameters related to the Rolling Update strategy.
Parameter Description Max Unavailable Pods
The maximum number or percentage of unavailable pod replicas allowed during the update process.
Max Extra Pods
The maximum number or percentage of extra pod replicas allowed during the update process.
-
Pod Settings > Pod Security Context
Set the permissions for all container processes in the pod within a Linux system. If both pod security context and container security context have set the user, group, and SELinux context, the settings in the container security context will override those in the pod security context.
Parameter Description User and User Group
The users and user groups running the entry point of container processes.
-
Run as Non-root: Checks if the container will run as the root user before starting. If the container is set to run as the root user, it won’t start. When this feature is enabled, the system will ignore the Privileged mode setting.
-
User: The UID (User ID) executing the container process entry point. Defaults to the UID specified in the image metadata.
-
User Group: The GID (Group ID) executing the container process entry point. Defaults to the default GID of the container runtime.
SELinux Context
The SELinux labels for the container process, including Level, Role, Type, and User. For more information, refer to the SELinux Documentation.
-
-
Pod Settings > Pod Scheduling Rules
Specify the rules for scheduling pod replicas to nodes.
Parameter Description Default Rules
No rules specified; The system determines which node the pod replicas should be scheduled to.
Decentralized Scheduling
Schedule pod replicas to different nodes whenever possible.
Centralized Scheduling
Schedule pod replicas to the same node whenever possible.
Custom Rules
Schedule pod replicas to nodes based on user-defined rules. If you choose this option, you need to further customize the scheduling rules.
-
Pod Settings > Pod Scheduling Rules > Custom Rules
Configure custom rules for pod scheduling.
-
Click Add to set multiple rules.
-
To delete a rule, Click
on the right of the created rule.
Parameter Description Type
The type of the rule.
-
Schedule with target : Pod replicas will be scheduled to the same node as other pods with specific labels in the current project.
-
Schedule away from target : Pod replicas will be scheduled to different nodes than other pods with specific labels in the current project.
Policy
The policy by which the rule is enforced.
-
Match if possible : Try to satisfy the rule as much as possible. If the rule cannot be satisfied, the pod replicas will be scheduled to nodes that do not meet the rule requirements.
-
Must match : Must satisfy the rule requirements. If the rule requirements cannot be met, the pod replicas will not be scheduled to any node.
Target
The target of the rule. Pod replicas will be scheduled to the same or different nodes as pods with the label app=<target> (<target> is the selected value here), depending on the rule’s type and policy.
-
-
Pod Settings > Pod Graceful Period
Set the waiting time before the pod terminates; the pod will be forcefully terminated after the specified timeout. The default value is 30 seconds.
-
Pod Settings > Add Metadata
Add metadata for the pod. Currently, you can only set annotations for the pod.
-
Click Add to set multiple annotations.
-
To delete an annotation, Click
on the right of the created annotation.
-
-
Storage Settings
Mount volumes, ConfigMaps, or Secrets for the container.
Parameter Description Add Persistent Volume Claim Template
Add Persistent Volume Claim templates for StatefulSets. The system will create separate Persistent Volume Claims and Persistent Volumes for each pod replica, and mount the Persistent Volumes to the specified containers in each pod replica. Only available for StatefulSets.
Mount Volume
Mount Persistent Volumes, temporary volumes, or HostPath volumes to the container.
Mount ConfigMap or Secret
Mount data from ConfigMaps or Secrets as a volume to the container.
-
Hover over the added volume or PVC template, then click
on the right to edit its settings. -
Hover over the mounted volume or PVC template, then click
on the right to delete it.
-
-
Storage Settings > Add Persistent Volume Claim Template
Create separate Persistent Volume Claims and Persistent Volumes for each pod replica using the Persistent Volume Claim template and mount the Persistent Volumes to containers. Only available for StatefulSets.
Parameter Description PVC Name Prefix
The prefix for the names of the Persistent Volume Claims created by the Persistent Volume Claim template. The system will automatically name the Persistent Volume Claims in the format
<Name Prefix>-<Workload Name>-<Sequence Number>. Persistent volume claims for different pod replicas in the same StatefulSet are distinguished by the <Sequence Number>.Storage Class
The storage class used to create the Persistent Volume Claims.
Access Mode
The access modes of Persistent Volumes.
-
RWO (ReadWriteOnce): Allows a single node to read from and write to the Persistent Volume.
-
ROX (ReadOnlyMany): Allows multiple nodes to read from the Persistent Volume.
-
RWX (ReadWriteMany): Allows multiple nodes to read from and write to the Persistent Volume.
Volume Capacity
The capacity of each Persistent Volume created by the Persistent Volume Claim template.
Mount Mode
The mount mode of the volume on the container.
-
Read and write: Allows the container to read from and write to the volume.
-
Read-only: Only allows the container to read from the volume.
-
Not mounted: 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 that needs 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 the container. The Persistent Volume Claim used to create the Persistent Volume must belong to the project where the container is located.
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 project where the container is located. If there is no available Persistent Volume Claim in the project of the container, you need to create one in advance.
Mount Mode
The mount mode of the volume on the container.
-
Read and write: Allows the container to read from and write to the volume.
-
Read-only: Only allows the container to read from the volume.
-
Not mounted: 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 that needs 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 the container. Temporary volumes have the following characteristics:
-
Automatically created by the system in the storage system of the node where the pod is located.
-
Automatically managed by the system, with a capacity limit equal to the storage capacity of the node.
-
Cannot save persistent data. The system automatically creates a temporary volume when the pod is created and automatically deletes the temporary volume when the pod is deleted.
Parameter Description Volume Name
The name of the temporary volume.
Mount Mode
The mount mode of the volume on the container.
-
Read and write: Allows the container to read from and write to the volume.
-
Read-only: Only allows the container to read from the volume.
-
Not mounted: 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 that needs to be mounted. If no subpath is set, the entire volume is mounted by default. -
-
Storage Settings > Mount Volume > HostPath Volume
Mount a file or directory on the node where the pod is located to the container using a HostPath volume.
-
Files or folders under the same path on different nodes may differ, so pod replicas on different nodes may read different data from the HostPath volume.
-
Ensure that the mounted path exists on the node where the pod is located, and the container process has the necessary permissions. Otherwise, the container process will be unable to read from or write to the data in the HostPath volume.
Parameter Description Volume Name
The name of the HostPath volume.
Host Path
The path to the file or folder on the node that needs to be mounted.
Mount Mode
The mount mode of the volume on the container.
-
Read and write: Allows the container to read from and write to the volume.
-
Read-only: Only allows the container to read from the volume.
-
Not mounted: 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 that needs to be mounted. If no subpath is set, the entire volume is mounted by default. -
-
Storage Settings > Mount ConfigMap or Secret
Mount data from ConfigMaps or Secrets as a volume to the container.
Parameter Description Select Configmap/Select Secret
Select the ConfigMap or Secret in the current project.
Mount Mode
Set the mount mode of the data from the ConfigMap or Secret on the container. Configmaps and Secrets only support mounting in Read-only mode or Not mounted.
Mount Path
Set the path where the data from the ConfigMap or Secret is mounted on the container.
-
The system will generate a folder based on the data from the ConfigMap or Secret and map each key-value pair to a file. Each file is named after the key, and the content is the value.
-
Click
to specify key-value pairs from the ConfigMap or Secret as files to be mounted. If no subpath is set, the entire ConfigMap or Secret is mounted by default. If a subpath is used, files mounted to the container will not dynamically update with changes in the ConfigMap or Secret.
Select Specific Keys
Mount key-value pairs from the ConfigMap or Secret as files to the container. Files mounted to the container will dynamically update with changes in the ConfigMap or Secret. Click Add to mount multiple key-value pairs.
-
Key: The key of the key-value pair in the ConfigMap or Secret to be mounted.
-
Path: The path relative to the Mount Path in the container. The specified key-value pair from the ConfigMap or Secret will be mounted to this path, and existing files in the Mount Path will be overwritten.
-
-
Advanced Settings
Specify nodes for the pods managed by the service backend workload, set the external access mode, session persistence settings, and metadata for the service.
Parameter Description External Access
The external access mode for the service.
-
NodePort: The system maps the ports of nodes to the service ports, and the service can be accessed through the node IP address and node port.
-
LoadBalancer: On the basis of a NodePort service, the system assigns an external IP address to the 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, allowing access to the service through the external IP address. To achieve this, LoadBalancer-type services need support from load balancer plugins and the infrastructure environment, and relevant annotations need to be set. For more information, please contact your infrastructure environment provider.
Session Persistence
Configure the system to forward all requests from the same client in the same session to the same pod within a specified duration. The default maximum stickiness duration is 10800 seconds, and you can also change it.
Select Nodes
Schedule pod replicas to nodes with specified labels.
-
You can manually enter key-value pairs for the labels of the target node, or click Specify Node to choose a node.
-
Click Add Node Selector to set multiple labels; pod replicas will be scheduled to nodes with all specified labels.
-
Click
on the right of a created label to delete it.
Add Metadata
Configure labels for the service and annotations for the backend workload.
-
Click Add to set multiple labels or annotations.
-
Click
on the right of a created label or annotation to delete it.
-
-
Cluster Differences
Differentiate the service based on containers, ports, and environment variables in different clusters.
Parameter Description Container Settings
Use different container settings in different clusters. In a multi-cluster environment, you can set different container images, container types, and resource configurations for the service in specified clusters.
Port Settings
Set different ports for containers in different clusters. In a multi-cluster environment, you can set different access protocols, container ports, and service ports for the service in specified clusters.
Environment Variables
Set different environment variables for containers in different clusters. In a multi-cluster environment, you can set different environment variables for the service in specified clusters.
Feedback
Was this page Helpful?
Receive the latest news, articles and updates from KubeSphere
Thanks for the feedback. If you have a specific question about how to use KubeSphere, ask it on Slack. Open an issue in the GitHub repo if you want to report a problem or suggest an improvement.
Previous
What’s on this Page