kubernetes.md

title	order
Kubernetes	2

Kubernetes

Garden can apply Kubernetes manifests via the kubernetes deploy action type. In many cases you'll want to use a kubernetes deploy action with a container build. You can do this by referencing the image ID of the container build in your Kubernetes manifests.

The kubernetes deploy action type works very similar to the helm deploy and you'll find a lot common between the two guides.

See the full spec for the kubernetes deploy action in our reference docs.

kubernetes-pod run, kubernetes-pod test and kubernetes-exec actions can be used for testing and task porposes.

Referencing manifests

When configuring a kubernetes deploy action, you have a choice between pointing Garden to the actual manifest files via the spec.files directive or simply adding the manifests inline in your Garden config under the spec.manifests directive.

Manifest files

If your project structure looks something like this:

.
├── api
│   ├── garden.yml
│   ├── manifests
│   │   ├── prod
│   │   ├── Deployment.yaml
│   │   ├── Ingress.yaml
│   │   └── Service.yaml
│   │   ├── dev
│   │   ├── Deployment.yaml
│   │   ├── Ingress.yaml
│   │   └── Service.yaml
│   └── src
└── project.garden.yml

You can reference the manifests like so:

kind: Deploy
type: kubernetes
name: api
spec:
  files:
    - ./manifests/Deployment.yaml
    - ./manifests/Ingress.yaml
    - ./manifests/Service.yaml

{% hint style="warning" %} Due to a current limitation you need to list all the manifests. There's an open issue for addressing this. {% endhint %}

You can also use templating to reference different manifests based on environment. For example, if your project structure looks like this:

.
├── api
│   ├── garden.yml
│   ├── manifests
│   │   ├── dev
│   │   │   ├── Deployment.yaml
│   │   │   ├── Ingress.yaml
│   │   │   └── Service.yaml
│   │   └── prod
│   │       ├── Deployment.yaml
│   │       ├── Ingress.yaml
│   │       └── Service.yaml
│   └── src
└── project.garden.yml

You can reference the manifests like so:

kind: Deploy
type: kubernetes
name: api
spec:
  files:
    - ./manifests/${environment.name}/Deployment.yaml
    - ./manifests/${environment.name}/Ingress.yaml
    - ./manifests/${environment.name}/Service.yaml

Inline

You can also include the manifests inline with your Garden configuration. For example:

kind: Deploy
type: kubernetes
name: api
spec:
  manifests:
  - apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: api
      labels:
        app: api
    spec:
      # ...

  - apiVersion: v1
    kind: Service
    metadata:
    labels:
      app: api
      name: api
    spec:
      # ...
  - apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: api
      labels:
        app: api
    spec:
      # ...

Using variables

Whether you have your manifests inline or reference them as files, you can use Garden template strings. For example:

# This will work inside api/garden.yml and manifests/garden.yml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
  labels:
    app: api
spec:
  replicas: ${var.numberOfReplicas}
  # ...

kubernetes-pod runs and tests

For tasks and tests either the kubernetes-pod or kubernetes-exec action types can be used.

kubernetes-pod run and kubernetes-pod test will create a fresh kubernetes workload and run your command in it. These actions are cached. This means that if garden will not rerun them if the version of the action hasn't changed. If a remote kubernetes cluster is used, test results are stored there which allows to share test results between the team or ci runs to decrease the number or re-runs.

kubernetes-pod actions don't have to depend on the deploy actions. The manifests are gathered from the kubernetes manifests and deployed to the cluster.

kind: Test
name: vote-integ-pod
type: kubernetes-pod
dependencies:
  - deploy.api
variables:
  hostname: vote.${var.baseHostname}
timeout: 60
spec:
  resource:
    kind: Deployment
    name: vote-integ-pod
  command: [/bin/sh, -c, "npm run test:integ"]
  values:
...

Linking container builds and kubernetes deploy actions

When your project also contains one or more container build actions that build the images used by a kubernetes deploy, you want to make sure the containers are built ahead of deploying the Helm chart, and that the correct image tag is used when deploying.

kind: Build
type: container
name: worker-image

kind: Deploy
description: Kubernetes deploy for the worker container
type: helm
name: worker-deploy
dependencies: [build.worker-image]
spec:
  manifests:
  - apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: worker
      labels:
        app: worker
      spec:
        containers:
        - name: worker
          image: ${actions.build.worker-image.outputs.deployment-image-id} # <--- Here we're referencing the output from the api-image Build. This will also work in manifest files.
          # ...

Here the worker-deploy injects the worker-image version into the kubernetes manifest with string templating.

This can also work if you use multiple containers in a deploy. You just add them all as dependencies.

Code Synchronization

Synchronization can be configured with kubernetes deploys. In the example below code synchronization is set up from the vote-image build action's directory.

kind: Deploy
type: kubernetes
name: myapp
...
spec:
  defaultTarget:
    kind: Deployment
    name: myapp
  sync:
    paths:
      - containerPath: /app/src
        sourcePath: ${actions.build.vote-image.sourcePath}/src
        mode: two-way

For more information on synchronization check out the Code Synchronization Guide.

Production environments

You can define a remote environment as a production environment by setting the production flag to true. This affects some default behavior when working with kubernetes actions. See the Deploying to production guide for details.

Next steps

Check out the full action reference for more details. Also check out the Helm action type for a more flexible alternative.