> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# fairwinds/rok8s-scripts

"rok8s-scripts is a framework for building git-triggered workflows with Docker and Kubernetes. By adding rok8s-scripts to your CI/CD pipeline, you can build, push, and deploy your applications using the set of best practices we’ve built at Fairwinds.

In addition to building Docker images and deploying them to Kubernetes, rok8s-scripts is a great way to handle secure secrets management, environment specific configuration, Docker build caching, and much more.


## Commands

### docker_build

Builds a docker image using rok8s-scripts

| Parameter | Type | Default | Description |
|---|---|---|---|
| `config` | string | deploy/build.config | The location of the rok8s-scripts config file |

### docker_login

Log into a docker repo

| Parameter | Type | Default | Description |
|---|---|---|---|
| `password-variable` | env_var_name |  | The environment variable name containing the password. |
| `registry` | string | quay.io | The name of the docker registry. |
| `username` | string |  | The username to use for the registry. |

### docker_push

Pushes a docker image using rok8s-scripts

| Parameter | Type | Default | Description |
|---|---|---|---|
| `config` | string | deploy/build.config | The location of the rok8s-scripts config file |

### e2e_run_script

Run a script in the executor.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `post_script` | string |  | Script to run on the local machine after running script on command runner. |
| `pre_script` | string |  | Script to run on the local machine before running script on command runner. |
| `script` | string |  | Script to run on the command runner. |

### e2e_start_command_runner

Start a command runner to execute commands against the kind cluster

| Parameter | Type | Default | Description |
|---|---|---|---|
| `command_runner_image` | string | quay.io/reactiveops/ci-images:v11-alpine | The image to execute commands from against the kind cluster. |

### e2e_start_kind_cluster

Start a kind cluster

| Parameter | Type | Default | Description |
|---|---|---|---|
| `kind_config` | string | kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
kubeadmConfigPatches:
- |
  apiVersion: kubeadm.k8s.io/v1beta3
  kind: ClusterConfiguration
  metadata:
    name: config
  apiServer:
    certSANs:
    - e2e-control-plane
    - 127.0.0.1
    - localhost
  etcd:
    serverCertSANs:
    - e2e-control-plane
    - 127.0.0.1
    - localhost
    peerCertSANs:
    - e2e-control-plane
    - 127.0.0.1
    - localhost
 | A Kind config file to use for the cluster |
| `kind_node_image` | string | kindest/node:v1.24.6@sha256:97e8d00bc37a7598a0b32d1fabd155a96355c49fa0d4d4790aab0f161bf31be1 | The kind node image to use.  See https://github.com/kubernetes-sigs/kind/releases |
| `kind_version` | string | 0.17.0 | The kind version to use. See https://github.com/kubernetes-sigs/kind/releases |

### get_vault_aws_credentials

Retrieves aws sts credentials from Vault and sets them as environment variables.
Requires that a VAULT_TOKEN and a VAULT_ADDR be set in your
environment. Also requires that the vault and yq binaries be available


| Parameter | Type | Default | Description |
|---|---|---|---|
| `vault_path` | string |  | The kv path to pull credentials from in Vault |

### get_vault_env

Retrieves environment variables from Vault and sets them.
Requires that a VAULT_TOKEN and a VAULT_ADDR be set in your
environment. Also requires that the vault binary be available


| Parameter | Type | Default | Description |
|---|---|---|---|
| `vault_path` | string |  | The kv path to pull env from in Vault |

### github_release

Create a Github Release from a git tag. Requires that GITHUB_ACCESS_TOKEN be set as an environment variable. If the tag is annotated, that will become the release notes. If the tag is not annotated, then a list of commits will become the release notes.


### set_env

Sets the needed rok8s-scripts environment variables from Circle

## Jobs

### docker_build_and_push

A workflow for building and pushing a docker image using rok8s-screipts. Assumes you have a working rok8s config file.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `checkout-method` | string | blobless | Valid options include blobless and full.
 |
| `checkout-path` | string | . | Where to checkout the repository.
 |
| `config_file` | string | deploy/build.config | The location of the rok8s-scripts config file. |
| `docker-login` | boolean | true | When true(default), perform a docker login before build and push. |
| `docker-push` | boolean | true | When true(default), push the image when done. |
| `enable_docker_layer_caching` | boolean | false | Enables docker_layer_caching on remote docker. Requires a paid plan. |
| `executor` | executor | ci-images | The name of custom executor to use. Only recommended for development. |
| `password-variable` | string |  | The environment variable name containing the password. Only used if docker-login is true. |
| `registry` | string | quay.io | The name of the docker registry. Only used if docker-login is true. |
| `username` | string |  | The username to use for the registry. Only used if docker-login is true. |

### github_release

Create a Github Release from a git tag. Requires that GITHUB_ACCESS_TOKEN be set as an environment variable. If the tag is annotated, that will become the release notes. If the tag is not annotated, then a list of commits will become the release notes.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `checkout-method` | string | blobless | Valid options include blobless and full.
 |
| `checkout-path` | string | . | Where to checkout the repository.
 |
| `executor` | executor | ci-images | The name of custom executor to use. Only recommended for development. |

### insights

Run a Fairwinds Insights Report. Requires that a FAIRWINDS_TOKEN be set in your environment variables.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `checkout-method` | string | blobless | Valid options include blobless and full.
 |
| `checkout-path` | string | . | Where to checkout the repository.
 |
| `executor` | executor | ci-images | The name of custom executor to use. Only recommended for development. |

### kubernetes_e2e_tests

sets up a working e2e testing environment for Kubernetes using kind and also sets up a way to access it via the e2e-command-runner container. There are two entrypoints for scripts here, one is a pre_script, and one is the script. The pre_script runs on the CircleCI executor itself and allows access to the repository that was checked out, as well as provides the opportunity to copy more files over to the command runner. This can be done using `docker cp <file> e2e-command-runner:<path>. The regular script is copied over to the command runner container and executed on the command runner, providing access to the Kubernetes kind cluster via kubectl and helm commands. The post_script runs on the CircleCI executor itself after the script is run on the command runner.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `attach-workspace` | boolean | false | If true, the attach_workspace step will be run before any other steps.
 |
| `checkout-method` | string | blobless | Valid options include blobless and full.
 |
| `checkout-path` | string | . | Where to checkout the repository.
 |
| `command_runner_image` | string | quay.io/reactiveops/ci-images:v15.0-alpine | The image to execute commands from against the kind cluster. Also where the script gets executed. |
| `enable_docker_layer_caching` | boolean | false | Enables docker_layer_caching on remote docker. Requires a paid plan. |
| `executor` | executor | ci-images | The name of custom executor to use. Only recommended for development. |
| `kind_config` | string | kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
kubeadmConfigPatches:
- |
  apiVersion: kubeadm.k8s.io/v1beta3
  kind: ClusterConfiguration
  metadata:
    name: config
  apiServer:
    certSANs:
    - e2e-control-plane
    - 127.0.0.1
    - localhost
  etcd:
    serverCertSANs:
    - e2e-control-plane
    - 127.0.0.1
    - localhost
    peerCertSANs:
    - e2e-control-plane
    - 127.0.0.1
    - localhost
 | A Kind config file to use for the cluster |
| `kind_node_image` | string | kindest/node:v1.24.6@sha256:97e8d00bc37a7598a0b32d1fabd155a96355c49fa0d4d4790aab0f161bf31be1 | The kind node image to use.  See https://github.com/kubernetes-sigs/kind/releases |
| `kind_version` | string | 0.17.0 | The kind version to use. See https://github.com/kubernetes-sigs/kind/releases |
| `post_script` | string |  | Script to run on the local machine after running script on command runner. |
| `post_script_steps` | steps |  | Define and inject a set of custom steps to run in the local machine after scripts are executed on the command runner. |
| `pre_script` | string |  | Script to run on the local machine before running script on command runner. |
| `pre_script_steps` | steps |  | Define and inject a set of custom steps to run in the local machine before scripts are executed on the command runner. |
| `script` | string |  | The script to run on the command runner. |
| `store-artifacts` | string |  | The location to store artifacts from. This path will be used in the command runner as well as
the executor, so it is recommended that you choose something like /tmp/output
 |
| `store-test-results` | string |  | The location to store test results. This path will be used in the command runner as well as
the executor, so it is recommended that you choose something like /tmp/test-results
 |
| `workspace-location` | string | /tmp/workspace | Where to mount the workspace if attach-workspace is true.
 |

## Executors

### ci-images

| Parameter | Type | Default | Description |
|---|---|---|---|
| `version` | string | v15.0-bullseye |  |

### default

| Parameter | Type | Default | Description |
|---|---|---|---|
| `version` | string | v15.0-bullseye |  |

## Examples

### docker_build_push

Use this example to build and push a docker image using rok8s-scripts.  This assumes that you have a working rok8s-scripts configuration already in place.


```yaml
orbs:
  rok8s-scripts: fairwinds/rok8s-scripts@11
version: 2.1
workflows:
  build_and_push:
    jobs:
      - rok8s-scripts/docker_build_and_push:
          config_file: deploy/build.config
          context: org-global
          docker-login: true
          filters:
            branches:
              only: master
          password-variable: quay_token
          registry: quay.io
          username: orgname+circleci
```

### kubernetes_e2e_tests

This is an example of how one might run an end-to-end test in Kubernetes using this Orb. There are two entrypoints for scripts here, one is a pre_script, and one is the script. The pre_script runs on the CircleCI executor itself and allows access to the repository that was checked out, as well as provides the opportunity to copy more files over to the command runner. This can be done using `docker cp <file> e2e-command-runner:<path>. The regular script is copied over to the command runner container and executed on the command runner, providing access to the Kubernetes kind cluster via kubectl and helm commands. The post_script runs on the CircleCI executor itself after the script is run on the command runner.


```yaml
orbs:
  rok8s-scripts: fairwinds/rok8s-scripts@11
version: 2.1
workflows:
  build:
    jobs:
      - rok8s-scripts/kubernetes_e2e_tests:
          filters:
            branches:
              only: /.*/
            tags:
              ignore: /.*/
          name: End-To-End Test on Kubernetes
          post_script: e2e/post.sh
          pre_script: e2e/pre.sh
          script: e2e/test.sh
  version: 2
```

### kubernetes_e2e_tests_multiple_versions

This example expands upon the kubernetes e2e test example by demonstrating how you could run the same test across multiple kubernetes versions.


```yaml
orbs:
  rok8s-scripts: fairwinds/rok8s-scripts@11
version: 2.1
workflows:
  build:
    jobs:
      - rok8s-scripts/kubernetes_e2e_tests:
          filters:
            branches:
              only: /.*/
            tags:
              ignore: /.*/
          kind_node_image: >-
            kindest/node:v1.15.6@sha256:18c4ab6b61c991c249d29df778e651f443ac4bcd4e6bdd37e0c83c0d33eaae78
          name: End-To-End Test Kube 1.15.6
          post_script: e2e/post.sh
          pre_script: e2e/pre.sh
          script: e2e/test.sh
      - rok8s-scripts/kubernetes_e2e_tests:
          filters:
            branches:
              only: /.*/
            tags:
              ignore: /.*/
          kind_node_image: >-
            kindest/node:v1.16.3@sha256:70ce6ce09bee5c34ab14aec2b84d6edb260473a60638b1b095470a3a0f95ebec
          name: End-To-End Test Kube 1.16.3
          post_script: e2e/post.sh
          pre_script: e2e/pre.sh
          script: e2e/test.sh
  version: 2
```

### use_single_command

This is an example of how you can use a single command from the orb to perform specific actions.
This particular example utilizes the executor and the set_env command from the orb. This can make utilizing existing rok8s-scripts commands that have not yet been implemented in the orb.


```yaml
jobs:
  deploy-secrets:
    executor: rok8s-scripts/ci-images
    steps:
      - checkout
      - rok8s-scripts/set_env
      - run: prepare-kubectl
      - run: k8s-deploy-secrets -f <PATH TO YOUR CONFIG>
orbs:
  rok8s-scripts: fairwinds/rok8s-scripts@11
version: 2.1
workflows:
  build:
    jobs:
      - deploy-secrets:
          filters:
            branches:
              only: /.*/
  version: 2
```