Sidecar

The sidecar trait adds a new container to the component following the sidecar pattern. A sidecar is a container that is co-deployed with the component container. Both container will be co-located and co-scheduled in the same cluster node. The containers can share resources and dependencies and communicate between them.

The most common use cases to include sidecars include:

  • Export logs from the main container reading the files from it in the sidecar one.
  • Using the sidecar as authentication and/or authorization proxies to access other services that required secure connections. For example, the main component can expect plain text communication with a local port, while the sidecar works as a proxy with the secured endpoint.
  • Export monitoring information with a sidecar that reads health status and metrics from the component and exports them into a monitoring system.

The sidecar trait is complex and supports all the required elements to launch a container.

Attaching a sidecar container

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: my-comp
      type: worker
      properties:
        image: my-app-image:v1.0.0
      traits:
        - type: sidecar # Set to sidecar
          properties:
            name: trait-name # (Required) name of the trait 
            image: my-side-image:v1.0.0 # (Required) side car image
            cmd: ["server", "run"] # (Optional) Commands to run in the container.
            args: ["arg1", "arg2"] # (Optional) Args in the sidecar.
            env: # (Optional) env in the sidecar
              # Direct variable
              - name: ENV_1 # Variable name
                value: value1
              # Variable from secret
              - name: ENV_2 # Variable name
                valueFrom:
                  secretKeyRef:
                    name: mysecret # Secret Name (existing one)
                    key: username # Secret Key 
              # Variable from configMap
              - name: ENV_3 # Variable name
                valueFrom:
                  configMapKeyRef:
                    name: game-demo # ConfigMap Name (existing one)
                    key: player_initial_lives  # ConfigMap Key  

Mounting volumes in the sidecar

A sidecar can mount a volume from the main container to have access to its files. The following YAML file contains a minimal example of a sidecar with a volume attached to it.

apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: my-app
spec:
  components:
    - name: my-comp
      type: worker
      properties:
        image: my-app-image:v1.0.0
      traits:
        - type: sidecar # Set to sidecar
          properties:
            name: trait-name # (Required) name of the trait 
            image: my-side-image:v1.0.0 # (Required) side car image 
            volumes:
              - name: varlog
                path: /var/log

Attaching probes

Probes allow the system to determine when the sidecar is ready to accept traffic, and when the sidecar is healthy. The later information can be used to automatically reboot the component. The following YAML file defines a sidecar with a readiness and liveness probe attached to it.

apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: my-app
spec:
  components:
    - name: my-comp
      type: worker
      properties:
        image: my-app-image:v1.0.0
      traits:
        - type: sidecar # Set to sidecar
          properties:
            name: trait-name # (Required) name of the trait 
            image: my-side-image:v1.0.0 # (Required) side car image
            livenessProbe: # (Optional) Definition of the liveness probe to determine the 
                           # health status of a component rebooting it if needed
              # Option 1
              exec: # (Optional)
                command: ["cmd"] # A command to be executed inside the container to evaluate container state. 
              # Option 2
              httpGet:
                path: /healthz
                port: 8080

              failureThreshold: 1 # Number of consecutive failures required to determine the container is not alive. Set to 3 by default
              periodSeconds: 5 # How often, in seconds, to execute the probe. Set to 10 by default
              initialDelaySeconds: 3 # Number of seconds after the container is started before the first
            readinessProbe: # (Optional) Definition of the readiness probe to determine the 
                       # if the component can accept traffic.
              # Option 1
              exec: # (Optional)
                command: ["cmd"] # A command to be executed inside the container to determine the if the component can accept traffic.
              # Option 2
              httpGet:
                path: /healthz
                port: 8080
              failureThreshold: 1 # Number of consecutive failures required to determine the container is not ready. Set to 3 by default
              periodSeconds: 5 # How often, in seconds, to execute the probe. Set to 10 by default
              initialDelaySeconds: 3 # Number of seconds after the container is started before the first

Full example

The following YAML shows a complete example of attaching a sidecar to a component.

apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: my-app
spec:
  components:
    - name: my-comp
      type: worker
      properties:
        image: my-app-image:v1.0.0
      traits:
        - type: sidecar # Set to sidecar
          properties:
            name: trait-name # (Required) name of the trait 
            image: my-side-image:v1.0.0 # (Required) side car image
            cmd: ["server", "run"] # (Optional) Commands to run in the container.
            args: ["arg1", "arg2"] # (Optional) Args in the sidecar.
            env: # (Optional) env in the sidecar
              # Direct variable
              - name: ENV_1 # Variable name
                value: value1
              # Variable from secret
              - name: ENV_2 # Variable name
                valueFrom:
                  secretKeyRef:
                    name: mysecret # Secret Name (existing one)
                    key: username # Secret Key 
              # Variable from configMap
              - name: ENV_3 # Variable name
                valueFrom:
                  configMapKeyRef:
                    name: game-demo # ConfigMap Name (existing one)
                    key: player_initial_lives  # ConfigMap Key  
            volumes:
              - name: varlog
                path: /var/log
            livenessProbe: # (Optional) Definition of the liveness probe to determine the 
                           # health status of a component rebooting it if needed
              # Option 1
              exec: # (Optional)
                command: ["cmd"] # A command to be executed inside the container to evaluate container state. 
              # Option 2
              httpGet:
                path: /healthz
                port: 8080
              failureThreshold: 1 # Number of consecutive failures required to determine the container is not alive. Set to 3 by default
              periodSeconds: 5 # How often, in seconds, to execute the probe. Set to 10 by default
              initialDelaySeconds: 3 # Number of seconds after the container is started before the first
            readinessProbe: # (Optional) Definition of the readiness probe to determine the 
                       # if the component can accept traffic.
              # Option 1
              exec: # (Optional)
                command: ["cmd"] # A command to be executed inside the container to determine the if the component can accept traffic.
              # Option 2
              httpGet:
                path: /healthz
                port: 8080
              failureThreshold: 1 # Number of consecutive failures required to determine the container is not ready. Set to 3 by default
              periodSeconds: 5 # How often, in seconds, to execute the probe. Set to 10 by default
              initialDelaySeconds: 3 # Number of seconds after the container is started before the first