Stateful service
A statefulservice component describes long-running, scalable application with guarantees about the ordering and uniqueness of the replicas. From the point of Kubernetes this type of component generates StatefulSet and Service.
This component offers similar properties to those found in webservice and worker.
Basic information
Basic information includes the image
that will be launched with an optional cmd
property to define a command different from the one in the image entrypoint. Additionally, the container can define the requested CPU and memory to better utilize the available quota. The following YAML file contains a minimal example of a worker with basic information.
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: my-app
spec:
components:
- name: backend # Name of the component
type: statefulservice # Set to statefulservice
properties:
image: my-app-image:v1.0.0 # (Required) Container image
env: # (Optional) Definition of the environment variables for the container
- name: ENV_VAR1 # Setting the value directly
value: "value1"
replicas: 1 # (Required) Replicas required
cmd: ["server", "run"] # (Optional) Commands to run in the container.
cpu: "0.5" # (Optional) Define the requested CPU.
memory: 256Mi # (Optional) Define the requested memory.
ports:
- port: 3306
expose: true
protocol: TCP
Using volumes
The system supports different methods to attach a volume to a container. The main use cases are:
- Attaching a persistent volume to store information that should survive container reboots.
- Attaching a configmap to include the configuration file in a given path.
- Attaching a secret to include files (e.g., TLS certificates) in a given path.
- Attaching an empty dir as ephemeral storage for temporal files.
The following YAML file contains a minimal example of a statefulservice component with different volumes attached to it.
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: my-app
spec:
components:
- name: backend # Name of the component
type: statefulservice # Set to statefulservice
properties:
image: my-app-image:v1.0.0 # (Required) Container image
replicas: 1 # (Required) Replicas required
volumeMounts: # (Optional) Definition of the volumes to be mounted
pvc: # Using a Persistent Volume Claim
- name: data
mountPath: "/var/lib/db"
claimName: "db-pvc"
size: 1Gi
configMap: # Using a Config Map
- name: cm-data
mountPath: "/config"
cmName: "db-config"
secret: # Using a Secret
- name: cert-data
mountPath: "/certs"
secretName: "db-certs"
emptyDir: # Using an ephemeral mount
- name: temp-data
mountPath: "/var/lib/tmp"
Defining probes
Probes allow the system to determine when a component is ready to accept traffic, and when the component is healthy. The later information can be used to automatically reboot the component. The following YAML file contains a webservice component with a readiness and liveness probe attached to it.
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: my-app
spec:
components:
- name: backend # Name of the component
type: statefulservice # Set to statefulservice
properties:
image: my-app-image:v1.0.0 # (Required) Container image
replicas: 1 # (Required) Replicas required
readinessProbe: # (Optional) Definition of the readiness probe to determine the
# if the component can accept traffic.
httpGet:
path: /healthz
port: 8080
initialDelaySeconds: 3 # Number of seconds after the container is started before the first
# probe is initiated. Set to 0 by default.
periodSeconds: 3 # How often, in seconds, to execute the probe. Set to 10 by default
livenessProbe: # (Optional) Definition of the liveness probe to determine the
# health status of a component rebooting it if needed
httpGet:
path: /healthz
port: 8080
initialDelaySeconds: 3 # Number of seconds after the container is started before the first
# probe is initiated. Set to 0 by default.
periodSeconds: 3 # How often, in seconds, to execute the probe. Set to 10 by default
Full example of a stateful service component
The following YAML shows a complete example of a webservice with all the major options.
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: my-app
spec:
components:
- name: backend # Name of the component
type: statefulservice # Set to statefulservice
properties:
image: my-app-image:v1.0.0 # (Required) Container image
replicas: 1 # (Required) Replicas required
ports: # Optional definition of the ports that are exposed by the container
- port: 80
expose: true # (Optional) Setting expose to true will generate a Service endpoint to
# enable component-to-component communication.
cmd: ["server", "run"] # (Optional) Commands to run in the container.
cpu: "0.5." # (Optional) Define the requested CPU.
memory: 256Mi # (Optional) Define the requested memory.
env: # (Optional) Definition of the environment variables for the container
- name: ENV_VAR1 # Setting the value directly
value: "value1"
- name: ENV_VAR2 # Using a secret to obtain a key value
valueFrom:
secretKeyRef:
name: secret-name
key: key2
- name: ENV_VAR3 # Using a configmap to obtain a key value
valueFrom:
configMapKeyRef:
name: config-map-name
key: key2
volumeMounts: # (Optional) Definition of the volumes to be mounted
pvc: # Using a Persistent Volume Claim
- name: data
mountPath: "/var/lib/db"
claimName: "db-pvc"
size: 1Gi
configMap: # Using a Config Map
- name: cm-data
mountPath: "/config"
cmName: "db-config"
secret: # Using a Secret
- name: cert-data
mountPath: "/certs"
secretName: "db-certs"
emptyDir: # Using an ephemeral mount
- name: temp-data
mountPath: "/var/lib/tmp"
readinessProbe: # (Optional) Definition of the readiness probe to determine the
# if the component can accept traffic.
httpGet:
path: /healthz
port: 8080
initialDelaySeconds: 3 # Number of seconds after the container is started before the first
# probe is initiated. Set to 0 by default.
periodSeconds: 3 # How often, in seconds, to execute the probe. Set to 10 by default
livenessProbe: # (Optional) Definition of the liveness probe to determine the
# health status of a component rebooting it if needed
httpGet:
path: /healthz
port: 8080
initialDelaySeconds: 3 # Number of seconds after the container is started before the first
# probe is initiated. Set to 0 by default.
periodSeconds: 3 # How often, in seconds, to execute the probe. Set to 10 by default