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

# circleci/kubernetes

A collection of tools for working with Kubernetes on CircleCI
View this orb's source: https://github.com/CircleCI-Public/kubernetes-orb


## Commands

### create_or_update_resource

Create or update a kubernetes resource.
Requirements: kubeconfig should be configured to connect to the cluster.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `action_type` | enum | apply | Specify whether to use `kubectl create` or `kubectl apply`
to create/update the resource.
 |
| `dry_run` | enum |  | Whether the kubectl command will be executed in dry_run mode.
Must be "none", "server", or "client"
 |
| `envsubst` | boolean | false | Whether to run envsubst to substitute environment variables inside
the deployment.yml finalizers.
 |
| `get_rollout_status` | boolean | false | Get the status of the rollout.
This can only be used for resource types that are valid
for usage with `kubectl rollout` subcommands.
 |
| `kustomize` | boolean | false | Enable it to run the kubectl command with the option -k for kustomize.
 |
| `namespace` | string |  | The kubernetes namespace that should be used.
 |
| `pinned_revision_to_watch` | string |  | Pin a specific revision to be watched and abort watching if it is rolled
over by another revision.
Only effective if get_rollout_status is set to true.
 |
| `resource_file_path` | string |  | Path to file used to create/update the resource.
 |
| `resource_name` | string |  | Resource name in the format TYPE/NAME e.g. deployment/nginx-deployment
This is required if get_rollout_status is set to true.
 |
| `server_side_apply` | boolean | false | Whether to run apply in the server instead of the client.
Only effective if action_type is set to `apply`.
 |
| `show_kubectl_command` | boolean | false | Whether to show the kubectl command used.
 |
| `watch_rollout_status` | boolean | true | Whether to watch the status of the latest rollout until it's done.
Only effective if get_rollout_status is set to true.
 |
| `watch_timeout` | string |  | The length of time to wait before ending the watch, zero means never.
Any other values should contain corresponding time unit (e.g 1s, 2m, 3h).
Only effective if get_rollout_status is set to true.
 |

### delete_resource

Delete kubernetes resource(s).
Requirements: kubeconfig should be configured to connect to the cluster.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `all` | boolean | false | If true, deletes all resources including uninitialized ones, in the
namespace of the specified resource types.
 |
| `cascade` | enum | background | If true, cascades the deletion of the resources managed by this resource.
(e.g. Pods created by a ReplicationController)
Must be "background" or "foreground"
 |
| `dry_run` | enum |  | Whether the kubectl command will be executed in dry_run mode.
Must be "none", "server", or "client"
 |
| `force` | boolean | false | Only used when "0" is specified for grace_period. If true, remove
resources from API and bypass graceful deletion. Note that immediate
deletion of some resources may result in inconsistency or data
loss and requires confirmation.
 |
| `grace_period` | integer | -1 | Period of time in seconds given to the resource to terminate gracefully.
A value of "-1" will be ignored.
 |
| `ignore_not_found` | boolean | false | If true, treats "resource not found" as a successful delete.
(Note: unlike the kubectl command, this does not default to true
when the "all" parameter value is set to true)
 |
| `kustomize` | boolean | false | Enable it to run the kubectl command with the option -k for kustomize.
 |
| `label_selector` | string |  | Use a label selector on the resource(s) to be deleted.
Effective only when the resource_types parameter is specified.
Cannot be used together with the resource_names parameter.
 |
| `namespace` | string |  | The kubernetes namespace that should be used.
 |
| `now` | boolean | false | If true, resources are signaled for immediate shutdown.
 |
| `resource_file_path` | string |  | Path to file used to describe the resource.
Should not be set when the "resource_types" parameter is specified.
 |
| `resource_names` | string |  | Specifies the names of resource(s) to be deleted.
Effective only when the resource_types parameter is specified.
Cannot be used together with the label_selector parameter.
 |
| `resource_types` | string |  | Specify what is to be deleted in the form of resource types.
This parameter is meant to be combined with either the
"resource_names" or the "label_selector" parameter.
e.g. use the value "pods,services" for "resource_types" and
the value "name=myLabel" for "label_selector" to delete pods and services
with the label name=myLabel.
e.g. use the value "pods,services" for "resource_types" and
the value "baz foo" for "resource_names" to delete pods and services
the match the names "baz" and "foo".

Should not be set when the "resource_file_path" parameter is specified.
 |
| `show_kubectl_command` | boolean | false | Whether to show the kubectl command used.
 |
| `wait` | boolean | true | If true, wait for resources to be gone before returning.
This waits for finalizers.
 |

### get_rollout_status

Gets the rollout status of a resource.
This command is only valid for resource types that are valid
for usage with `kubectl rollout` subcommands.
Requirements: kubeconfig should be configured to connect to the cluster.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `namespace` | string |  | The kubernetes namespace that should be used.
 |
| `pinned_revision_to_watch` | string |  | Pin a specific revision to be watched and abort watching if it is rolled
over by another revision.
 |
| `resource_file_path` | string |  | Path to file used to get the status of the resource.
 |
| `resource_name` | string |  | Resource name in the format TYPE/NAME e.g. deployment/nginx-deployment
 |
| `show_kubectl_command` | boolean | false | Whether to show the kubectl command used.
 |
| `watch_rollout_status` | boolean | true | Whether to watch the status of the latest rollout until it's done.
 |
| `watch_timeout` | string |  | The length of time to wait before ending the watch, zero means never.
Any other values should contain a corresponding
time unit (e.g. 1s, 2m, 3h).
 |

### install

Installs kubectl and kops (latest releases, by default)
Requirements: curl


| Parameter | Type | Default | Description |
|---|---|---|---|
| `kops_version` | string | latest |  |
| `kubectl_version` | string | latest | specify version using vX.Y.Z (e.g., v1.29.0) format.
 |
| `max_time` | boolean | false | This parameter will enable the curl command to not timeout for 600 seconds
 |

### install_kops

Installs kops (latest release, by default)
Requirements: curl


| Parameter | Type | Default | Description |
|---|---|---|---|
| `kops_version` | string | latest |  |

### install_kubeconfig

Install kubeconfig file with the contents taken from the value of an
environment variable, which should be base64-encoded.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `kubeconfig` | env_var_name | KUBECONFIG_DATA | Environment variable containing base64-encoded kubeconfig data |

### install_kubectl

Installs kubectl (latest release, by default)
Requirements: curl


| Parameter | Type | Default | Description |
|---|---|---|---|
| `kubectl_version` | string | latest | specify version using vX.Y.Z (e.g., v1.29.0) format.
 |
| `max_time` | boolean | false | This parameter will enable the curl command to not timeout for 600 seconds
 |

### rollback

Rollback a deployment or daemonset resource.
Requirements: kubeconfig should be configured to connect to the cluster.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `get_rollout_status` | boolean | false | Get the status of the rollout.
This can only be used for resource types that are valid
for usage with `kubectl rollout` subcommands.
 |
| `namespace` | string |  | The kubernetes namespace that should be used.
 |
| `resource_name` | string |  | Resource name in the format TYPE/NAME e.g. deployment/nginx-deployment
 |
| `show_kubectl_command` | boolean | false | Whether to show the kubectl command used.
 |
| `watch_rollout_status` | boolean | true | Whether to watch the status of the latest rollout until it's done.
 |
| `watch_timeout` | string |  | The length of time to wait before ending the watch, zero means never.
Any other values should contain a corresponding
time unit (e.g. 1s, 2m, 3h).
 |

### update_container_image

Updates existing container image(s) of resources on the cluster using the
`kubectl set image` command.
Requirements: kubeconfig should be configured to connect to the cluster.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `container_image_updates` | string |  | Specify a list of container image updates
(space-delimited name value pairs in the form
CONTAINER_NAME_1=CONTAINER_IMAGE_1 ... CONTAINER_NAME_N=CONTAINER_IMAGE_N)
to be applied to the resource via `kubectl set image`.
e.g. "busybox=busybox nginx=nginx:1.9.1"
 |
| `dry_run` | enum |  | Whether the kubectl command will be executed in dry_run mode.
 |
| `get_rollout_status` | boolean | false | Get the status of the rollout.
This can only be used for resource types that are valid
for usage with `kubectl rollout` subcommands.
 |
| `namespace` | string |  | The kubernetes namespace that should be used.
 |
| `pinned_revision_to_watch` | string |  | Pin a specific revision to be watched and abort watching if it is rolled
over by another revision.
Only effective if get_rollout_status is set to true.
 |
| `resource_file_path` | string |  | Path to file used to update the resource.
Either resource_file_path or resource_name need to be specified.
 |
| `resource_name` | string |  | Resource name in the format TYPE/NAME e.g. deployment/nginx-deployment
Either resource_file_path or resource_name need to be specified.
This is required if get_rollout_status is set to true.
 |
| `show_kubectl_command` | boolean | false | Whether to show the kubectl command used.
 |
| `watch_rollout_status` | boolean | true | Whether to watch the status of the latest rollout until it's done.
Only effective if get_rollout_status is set to true.
 |
| `watch_timeout` | string |  | The length of time to wait before ending the watch, zero means never.
Any other values should contain a corresponding
time unit (e.g. 1s, 2m, 3h). Only effective if
get_rollout_status is set to true.
 |

## Examples

### delete

Delete kubernetes resource.


```yaml
version: '2.1'
orbs:
  kubernetes: circleci/kubernetes@x.y.z
jobs:
  delete:
    docker:
      - image: cimg/base:stable
    steps:
      - kubernetes/install_kubectl
      - kubernetes/delete_resource:
          now: true
          resource_names: nginx-deployment
          resource_types: deployments
          wait: true
workflows: null
```

### deployment

Deploying kubernetes resources.


```yaml
version: '2.1'
orbs:
  kubernetes: circleci/kubernetes@x.y.z
jobs:
  create-update:
    docker:
      - image: cimg/base:stable
    steps:
      - checkout
      - kubernetes/install_kubectl
      - kubernetes/create_or_update_resource:
          get_rollout_status: true
          resource_file_path: tests/nginx-deployment/deployment.yaml
          resource_name: deployment/nginx-deployment
          show_kubectl_command: true
workflows: null
```

### deployment_update

Update kubernetes resource.


```yaml
version: '2.1'
orbs:
  kubernetes: circleci/kubernetes@x.y.z
jobs:
  update:
    docker:
      - image: cimg/base:stable
    steps:
      - checkout
      - kubernetes/install_kubectl
      - kubernetes/update_container_image:
          container_image_updates: nginx=nginx:1.9.1
          get_rollout_status: true
          resource_name: deployment/nginx-deployment
workflows: null
```

### install

Install kops and kubectl


```yaml
version: '2.1'
orbs:
  kubernetes: circleci/kubernetes@x.y.z
jobs:
  build:
    macos:
      xcode: '13.2'
    steps:
      - checkout
      - kubernetes/install
workflows: null
```

### install_kops

Install kops


```yaml
version: '2.1'
orbs:
  kubernetes: circleci/kubernetes@x.y.z
jobs:
  build:
    macos:
      xcode: '13.2'
    steps:
      - checkout
      - kubernetes/install_kops
workflows: null
```

### install_kubeconfig

Install kubeconfig


```yaml
version: '2.1'
orbs:
  kubernetes: circleci/kubernetes@1.0.0
jobs:
  build:
    macos:
      xcode: '13.2'
    steps:
      - checkout
      - kubernetes/install_kubeconfig:
          kubeconfig: KUBECONFIG_DATA
workflows: null
```

### install_kubectl

Install kubectl


```yaml
version: '2.1'
orbs:
  kubernetes: circleci/kubernetes@x.y.z
jobs:
  build:
    macos:
      xcode: '13.2'
    steps:
      - checkout
      - kubernetes/install_kubectl
workflows: null
```