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