drone-gke Usage

Use this plugin to deploy Docker images to Google Container Engine (GKE).

API Reference

The following parameters are used to configure this plugin:

`image`

type string

default ''

description reference to a drone-gke Docker image

example

# .drone.yml
---
pipeline:
  # ...
  deploy:
    image: nytimes/drone-gke:k8s-1.11
    # ...

`project`

type string

default ''

description GCP project ID; owner of the GKE cluster

notes default inferred from the service account credentials provided via token

example

# .drone.yml
---
pipeline:
  # ...
  deploy:
    image: nytimes/drone-gke
    project: my-gcp-project
    # ...

`zone`

type string

default ''

description GCP zone where GKE cluster is located

notes required if region is not provided

example

# .drone.yml
---
pipeline:
  # ...
  deploy:
    image: nytimes/drone-gke
    zone: us-east1-b
    # ...

`region`

type string

default ''

description GCP region where GKE cluster is located

notes required if zone is not provided

example

# .drone.yml
---
pipeline:
  # ...
  deploy:
    image: nytimes/drone-gke
    region: us-west1
    # ...

`cluster`

type string

default ''

description name of GKE cluster

notes required

example

# .drone.yml
---
pipeline:
  # ...
  deploy:
    image: nytimes/drone-gke
    cluster: prod
    # ...

`template`

type string

default '.kube.yml'

description path to Kubernetes manifest template

notes rendered using the Go text/template package

example

# .drone.yml
---
pipeline:
  # ...
  deploy:
    image: nytimes/drone-gke
    template: k8s/app.yaml
    # ...

`secret_template`

type string

default '.kube.sec.yml'

description path to Kubernetes Secret resource manifest template

notes rendered using the Go text/template package

example

# .drone.yml
---
pipeline:
  # ...
  deploy:
    image: nytimes/drone-gke
    secret_template: my-templates/secrets.yaml
    # ...

`wait_deployments`

type []string

default []

description wait for the given deployments using kubectl rollout status ...

notes deployments can be specified as "<type>/<name>" as expected by kubectl. If just "<name>" is given it will be defaulted to "deployment/<name>".

example

# .drone.yml
---
pipeline:
  # ...
  deploy:
    image: nytimes/drone-gke
    wait_deployments:
    - deployment/app
    - statefulset/memcache
    - nginx
    # ...

`wait_seconds`

type int

default 0

description number of seconds to wait before failing the build

notes ignored if wait_deployments is not set

example

# .drone.yml
---
pipeline:
  # ...
  deploy:
    image: nytimes/drone-gke
    wait_seconds: 180
    wait_deployments:
    - app
    - nginx
    - memcache
    # ...

`vars`

type map[string]interface{}

default

{
  // from $DRONE_BUILD_NUMBER
  "BUILD_NUMBER": "",
  // from $DRONE_COMMIT
  "COMMIT": "",
  // from $DRONE_BRANCH
  "BRANCH": "",
  // from $DRONE_TAG
  "TAG": "",
  // from `project`
  "project": "",
  // from `zone`
  "zone": "",
  // from `cluster`
  "cluster": "",
  // from `namespace`
  "namespace": "",
}

description variables to use in template and secret_template

notes see "Available vars" for details

example

# .drone.yml
---
pipeline:
  # ...
  deploy:
    image: nytimes/drone-gke
    vars:
      app_name: echo
      app_image: gcr.io/google_containers/echoserver:1.4
      env: dev
    # ...

`secrets`

type map[string]string

default {}

description variables to use in secret_template; credentials for drone-gke

notes TOKEN is required; see "Using secrets" for details

example

# .drone.yml
---
pipeline:
  # ...
  deploy:
    image: nytimes/drone-gke
    secrets:
    # custom secrets; only available within `secret_template`
    - source: APP_API_KEY_DEV
      target: SECRET_APP_API_KEY
    - source: BASE64_P12_CERT_DEV
      target: SECRET_BASE64_P12_CERT
    # required by `drone-gke`; not available within templates
    - source: DRONE_GKE_SERVICE_ACCOUNT_KEY_DEV
      target: TOKEN
    # ...

`expand_env_vars`

type bool

default false

description expand environment variables for values in vars for reference

notes only available for vars of type string; use $${var_to_expand} instead of ${var_to_expand} (two $$) to escape drone's variable substitution

example

# .drone.yml
---
pipeline:
  # ...
  deploy:
    image: nytimes/drone-gke
    environment:
    # ;)
    - PS1='C:${PWD//\//\\\\}>'
    vars:
      # CLOUD_SDK_VERSION (set by google/cloud-sdk) will be expanded
      message: "deployed using gcloud v$${CLOUD_SDK_VERSION}"
      # PS1 (set using standard drone `environment` field) will be expanded
      prompt: "cmd.exe $${PS1}"
      # HOSTNAME and PATH (set by shell) will not be expanded; the `hostnames` and `env` vars are set to non-string values
      hostnames:
      - example.com
      - blog.example.com
      - "$${HOSTNAME}"
      env:
        path: "$${PATH}"
    # ...

`kubectl_version`

type string

default ''

description version of kubectl executable to use

notes see Using "extra" kubectl versions for details

example

# .drone.yml
---
pipeline:
  # ...
  deploy:
    image: nytimes/drone-gke
    kubectl_version: "1.14"
    # ...

`dry_run`

type bool

default false

description do not apply the Kubernetes templates

example

# .drone.yml
---
pipeline:
  # ...
  deploy:
    image: nytimes/drone-gke
    dry_run: true
    # ...

`verbose`

type bool

default false

description dump available vars and the generated Kubernetes template

notes excludes secrets

example

# .drone.yml
---
pipeline:
  # ...
  deploy:
    image: nytimes/drone-gke
    verbose: true
    # ...

Service Account Credentials

drone-gke requires a Google service account and uses its JSON credential file to authenticate.

This must be passed to the plugin under the target token.

The plugin infers the GCP project from the JSON credentials (token) and retrieves the GKE cluster credentials.

Setting the JSON token

Improved in Drone 0.5+, it is no longer necessary to align the JSON file.

GUI

Simply copy the contents of the JSON credentials file and paste it directly in the input field (for example for a secret named GOOGLE_CREDENTIALS).

CLI

drone secret add \
  --event push \
  --event pull_request \
  --event tag \
  --event deployment \
  --repository org/repo \
  --name GOOGLE_CREDENTIALS \
  --value @gcp-project-name-key-id.json

Cluster Credentials

The plugin attempts to fetch credentials for authenticating to the cluster via kubectl.

If connecting to a regional cluster, you must provide the region parameter to the plugin and omit the zone parameter.

If connecting to a zonal cluster, you must provide the zone parameter to the plugin and omit the region parameter.

The zone and region parameters are mutually exclusive; providing both to the plugin for the same execution will result in an error.

Using `secrets`

drone-gke also supports creating Kubernetes secrets for you. These secrets should be passed from Drone secrets to the plugin as environment variables with targets with the prefix secret_. These secrets will be used as variables in the secret_template in their environment variable form (uppercased).

Kubernetes expects secrets to be base64 encoded, drone-gke does that for you. If you pass in a secret that is already base64 encoded, please apply the prefix secret_base64_ and the plugin will not re-encode them.

Available vars

These variables are always available to reference in any manifest, and cannot be overwritten by vars or secrets:

{
  "BRANCH": "master",
  "BUILD_NUMBER": "12",
  "COMMIT": "4923x0c3380413ec9288e3c0bfbf534b0f18fed1",
  "TAG": "",
  "cluster": "my-gke-cluster",
  "namespace": "",
  "project": "my-gcp-proj",
  "zone": "us-east1-a"
}

Expanding environment variables

It may be desired to reference an environment variable for use in the Kubernetes manifest. In order to do so in vars, the expand_env_vars must be set to true.

For example when using drone deploy org/repo 5 production -p IMAGE_VERSION=1.0, to get IMAGE_VERSION in vars:

expand_env_vars: true
vars:
  image: my-image:$${IMAGE_VERSION}

The plugin will expand the environment variable for the template variable.

To use $${IMAGE_VERSION} or $IMAGE_VERSION, see the Drone docs about preprocessing. ${IMAGE_VERSION} will be preprocessed to an empty string.

Using "extra" `kubectl` versions

tl;dr

To run drone-gke using a different version of kubectl than the default, set kubectl-version to the version you'd like to use.

For example, to use the 1.14 version of kubectl:

image: nytimes/drone-gke
kubectl_version: "1.14"

This will configure the plugin to execute /google-cloud-sdk/bin/kubectl.1.14 instead of /google-cloud-sdk/bin/kubectl for all kubectl commands.

Background

Beginning with the 237.0.0 (2019-03-05) release of the gcloud SDK, "extra" kubectl versions are installed automatically when kubectl is installed via gcloud components install kubectl.

These "extra" versions are installed alongside the SDK's default kubectl version at /google-cloud-sdk/bin and are named using the following pattern:

kubectl.$clientVersionMajor.$clientVersionMinor

To list all of the "extra" kubectl versions available within a particular version of drone-gke, you can run the following:

# list "extra" kubectl versions available with nytimes/drone-gke
docker run \
  --rm \
  --interactive \
  --tty \
  --entrypoint '' \
  nytimes/drone-gke list-extra-kubectl-versions

Example reference usage

`.drone.yml`

Note particularly the gke: build step.

---
pipeline:
  build:
    image: golang:1.8
    environment:
      - GOPATH=/drone
      - CGO_ENABLED=0
    commands:
      - go get -t
      - go test -v -cover
      - go build -v -a
    when:
      event:
        - push
        - pull_request
  gcr:
    image: plugins/gcr
    registry: us.gcr.io
    repo: us.gcr.io/my-gke-project/my-app
    tag: ${DRONE_COMMIT}
    secrets: [google_credentials]
    when:
      event: push
      branch: master

  gke:
    image: nytimes/drone-gke
    zone: us-central1-a
    cluster: my-gke-cluster
    namespace: ${DRONE_BRANCH}
    environment:
      - USER=root
    expand_env_vars: true
    vars:
      image: gcr.io/my-gke-project/my-app:${DRONE_COMMIT}
      app: my-app
      env: dev
      user: $${USER}
    secrets:
      - source: GOOGLE_CREDENTIALS
        target: token
      - source: APP_API_KEY
        target: secret_api_token
      - source: P12_CERT
        target: secret_base64_p12_cert
    when:
      event: push
      branch: master

`.kube.yml`

Note the two Kubernetes yml resource manifests separated by ---.

---
apiVersion: extensions/v1beta1
kind: Deployment

metadata:
  name: {{.app}}-{{.env}}

spec:
  replicas: 3
  template:
    metadata:
      labels:
        app: {{.app}}
        env: {{.env}}
    spec:
      containers:
        - name: app
          image: {{.image}}
          ports:
            - containerPort: 8000
          env:
            - name: APP_NAME
              value: {{.app}}
            - name: USER
              value: {{.user}}
            - name: APP_API_KEY
              valueFrom:
                secretKeyRef:
                  name: {{.app}}-{{.env}}
                  key: app-api-key
---
apiVersion: v1
kind: Service

metadata:
  name: {{.app}}-{{.env}}

spec:
  type: LoadBalancer
  selector:
    app: {{.app}}
    env: {{.env}}
  ports:
    - name: http
      protocol: TCP
      port: 80
      targetPort: 8000

`.kube.sec.yml`

Note that the templated output will not be dumped when debugging.

---
apiVersion: v1
kind: Secret

metadata:
  name: {{.app}}-{{.env}}

type: Opaque

data:
  app-api-key: {{.SECRET_APP_API_KEY}}
  p12-cert: {{.SECRET_BASE64_P12_CERT}}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOCS.md

DOCS.md

drone-gke Usage

API Reference

`image`

`project`

`zone`

`region`

`cluster`

`template`

`secret_template`

`wait_deployments`

`wait_seconds`

`vars`

`secrets`

`expand_env_vars`

`kubectl_version`

`dry_run`

`verbose`

Service Account Credentials

Setting the JSON token

GUI

CLI

Cluster Credentials

Using `secrets`

Available vars

Expanding environment variables

Using "extra" `kubectl` versions

tl;dr

Background

Example reference usage

`.drone.yml`

`.kube.yml`

`.kube.sec.yml`

Files

DOCS.md

Latest commit

History

DOCS.md

File metadata and controls

drone-gke Usage

API Reference

image

project

zone

region

cluster

template

secret_template

wait_deployments

wait_seconds

vars

secrets

expand_env_vars

kubectl_version

dry_run

verbose

Service Account Credentials

Setting the JSON token

GUI

CLI

Cluster Credentials

Using secrets

Available vars

Expanding environment variables

Using "extra" kubectl versions

tl;dr

Background

Example reference usage

.drone.yml

.kube.yml

.kube.sec.yml

`image`

`project`

`zone`

`region`

`cluster`

`template`

`secret_template`

`wait_deployments`

`wait_seconds`

`vars`

`secrets`

`expand_env_vars`

`kubectl_version`

`dry_run`

`verbose`

Using `secrets`

Using "extra" `kubectl` versions

`.drone.yml`

`.kube.yml`

`.kube.sec.yml`