This document explains how to inspect existing stateless workloads running in a
Google Distributed Cloud (GDC) air-gapped Kubernetes cluster. Stateless workloads let you
run your application deployment without having to store data or application
state. You can view your stateless workloads with the GDC console or
the kubectl CLI to monitor resource usage and workload health.

This document is for developers within the application operator group, who are
responsible for managing 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 view and inspect
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

Ask your IAM Project Admin to grant you the following roles in your project
namespace based on the task to perform:

- **Workload Viewer** (`workload-viewer`): view all workloads deployed to a shared cluster.
- **Namespace Admin** (`namespace-admin`): create, delete, edit, or view workloads in a shared cluster project namespace.

These roles are 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.

## View a project's container workloads

To view your project's container workloads, complete the following:

### Console

- In the navigation menu, select **Kubernetes Engine \> Workloads**.

  You can view details for your container workloads, such as the following:
  - Name
  - Type
  - Number of pods
  - Kubernetes cluster
  - Last modified date

  The container workloads are organized by which Kubernetes cluster they
  belong to. Select the **Cluster** drop-down to switch the cluster context.

### kubectl

- Run the following command to list all pods in your project:

  ```bash
  kubectl get pods -n PROJECT_NAMESPACE
  ```

  The output is similar to the following:

      NAME                        READY   STATUS    RESTARTS   AGE
      nginx-workload-ah-aa-1228   1/1     Running   0          12h
      nginx-workload-ah-ab-6784   1/1     Running   0          11h
      nginx-workload-ah-ac-0045   1/1     Running   0          12h

## Inspect the deployment

To request more detailed information about the components of a `Deployment`
resource, run commands that directly target the entity you're looking to
inspect.

### Get `Deployment` object information

To get detailed information about the `Deployment` object, run:

```bash
kubectl --kubeconfig KUBERNETES_CLUSTER_KUBECONFIG -n NAMESPACE \
    describe 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.

### Display live configuration in YAML format

To view a `Deployment` object's manifest, run:

```bash
kubectl --kubeconfig KUBERNETES_CLUSTER_KUBECONFIG -n NAMESPACE \
    get deployments DEPLOYMENT_NAME -o yaml
```

This command displays the `Deployment` object's live configuration in YAML
format.

### List pods

To list the `Pod` objects created by the deployment, run:

```bash
kubectl --kubeconfig KUBERNETES_CLUSTER_KUBECONFIG -n NAMESPACE \
    get pods -l KEY=VALUE
```

In this command, the `-l` flag lists all `Pod` objects with the specified
key-value pair label in the specified cluster.

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.

- `KEY`: the key for the key-value pair label set in the
  deployment. For example, if the `.template.metadata.labels` field has the
  `app: myapp` label configured, the key is `app`.

- `VALUE`: the value for the key-value pair label set in
  the deployment. For example, if the `.template.metadata.labels` field has the
  `app: myapp` label configured, the value is `my-app`.

For example, if you labeled the `Deployment` object `app: my-app`, you'd run the
following command to see `Pod` objects with that label:

```bash
kubectl --kubeconfig /tmp/kubeconfig.yaml -n my-namespace \
    get pods -l app=my-app
```

### Get specific pod information

To get information about a specific `Pod` object, run:

```bash
kubectl --kubeconfig KUBERNETES_CLUSTER_KUBECONFIG -n NAMESPACE \
    describe pod POD_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.

- `POD_NAME`: the name of the pod managed by the
  deployment.

## What's next

- [Update stateless workloads](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/containers/update-stateless-workloads.md.txt)
- [Scale stateless workloads](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/containers/scale-stateless-workloads.md.txt)
- [Manage node pools](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/platform/pa-user/manage-node-pools.md.txt)