This document explains how to update existing stateless workloads running in a
Google Distributed Cloud (GDC) air-gapped Kubernetes cluster. As your application evolves
based on resource usage and configuration optimizations, you must update your
underlying pod specification in the Kubernetes cluster to reflect those workload
changes.

This document is for developers within the application operator group, who are
responsible for updating application workloads for their organization. For more
information, see
[Audiences for GDC air-gapped documentation](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/resources/audiences.md.txt).

## Before you begin

To complete the tasks in this document, you must request the necessary
permissions and prepare your environment.

### Request IAM roles

You must have specific roles to get the permissions you need to update stateless
workloads. The roles you require depend on whether you are working within an
organization-scoped shared cluster or project-scoped standard cluster. For more
information, see
[Kubernetes cluster configurations](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/platform/pa-user/cluster-configs.md.txt).

#### Shared cluster roles

To create, delete, edit, or view workloads in a shared cluster, ask your IAM
Project Admin to grant you the **Namespace Admin** (`namespace-admin`) role.
This
role is bound to your project namespace.

#### Standard cluster roles

To create, delete, edit, or view workloads in a standard cluster, ask your
IAM Project Admin to grant you the **Cluster Developer** (`cluster-developer`)
role. This role is bound to your project namespace.

### Prepare your environment

To run commands against a
[Kubernetes cluster](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/platform/pa-user/clusters.md.txt#cluster-architecture)
using the API, make sure you have the following resources:

- Locate the Kubernetes cluster name, or ask a member of the platform
  administrator group what the cluster name is.

- [Sign in and generate](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/iam/sign-in.md.txt#zonal-cluster-kubeconfig)
  the kubeconfig file for the Kubernetes cluster.

- Use the kubeconfig path of the Kubernetes cluster to replace
  `KUBERNETES_CLUSTER_KUBECONFIG` in these
  instructions.

## Update the deployment

To update a `Deployment` object, run:

```bash
kubectl --kubeconfig KUBERNETES_CLUSTER_KUBECONFIG -n NAMESPACE \
    apply -f DEPLOYMENT_FILE
```

Replace the following:

- `KUBERNETES_CLUSTER_KUBECONFIG`: the kubeconfig file for the
  cluster running the deployment.

- `NAMESPACE`: the namespace. For shared clusters, this
  must be a project namespace. For standard clusters, it can be any namespace.

- `DEPLOYMENT_FILE`: the name of the `Deployment`
  manifest file to update.

The `kubectl apply` command applies a manifest file to a resource. If the
specified resource does not exist, it is created by the command.

There are also several other ways to update resources within your deployment.

### Update a container image

To change the image of a `Deployment` object, run:

```bash
kubectl --kubeconfig KUBERNETES_CLUSTER_KUBECONFIG -n NAMESPACE \
    set image deployment DEPLOYMENT_NAME \
    IMAGE=IMAGE:TAG
```

Replace the following:

- `KUBERNETES_CLUSTER_KUBECONFIG`: the kubeconfig file for the
  cluster running the deployment.

- `NAMESPACE`: the namespace. For shared clusters, this
  must be a project namespace. For standard clusters, it can be any namespace.

- `DEPLOYMENT_NAME`: the name of the `Deployment` object
  containing the image.

- `IMAGE`: the name of the container image.

- `TAG`: the tag to update for the container image.

Updating the image of a deployment is useful to change selector fields or
resources, such as requests or limits.

For example, to update a `Deployment` object named `nginx` to use version
`1.9.1`, run:

```bash
kubectl --kubeconfig /tmp/kubeconfig.yaml -n my-namespace \
    set image deployment nginx nginx=nginx:1.9.1
```

### Roll back an update

If you want to roll back an update, such as when your deployment becomes
unstable, use the `kubectl` CLI. A `Deployment` object's rollout history is
preserved in the system so you can roll back at any time.

To roll back an in-progress or completed update to its previous revision,
run:

```bash
kubectl --kubeconfig KUBERNETES_CLUSTER_KUBECONFIG \
    -n NAMESPACE \
    rollout undo deployment DEPLOYMENT_NAME
```

Replace the following:

- `KUBERNETES_CLUSTER_KUBECONFIG`: the kubeconfig file for the
  cluster running the deployment.

- `NAMESPACE`: the namespace. For shared clusters, this
  must be a project namespace. For standard clusters, it can be any namespace.

- `DEPLOYMENT_NAME`: the name of the `Deployment` object
  to roll back.

To roll back to a specific revision, run:

```bash
kubectl --kubeconfig KUBERNETES_CLUSTER_KUBECONFIG \
    -n NAMESPACE \
    rollout undo deployment DEPLOYMENT_NAME \
    --to-revision=REVISION_NUMBER
```

Replace the following:

- `KUBERNETES_CLUSTER_KUBECONFIG`: the kubeconfig file for the
  cluster running the deployment.

- `NAMESPACE`: the namespace. For shared clusters, this
  must be a project namespace. For standard clusters, it can be any namespace.

- `DEPLOYMENT_NAME`: the name of the `Deployment` object
  to roll back.

- `REVISION_NUMBER`: the integer that defines the
  revision to roll back to, such as `3`.

## What's next

- [Upgrade a cluster](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/platform/pa-user/upgrade-cluster.md.txt)
- [Isolate container workloads](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/platform/pa-user/isolate-container-workloads.md.txt)
- [Maintain Kubernetes clusters](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/platform-application/pa-ao-operations/cluster.md.txt)