Skip to content

Commit

Permalink
docs: update docs for v1.0.0-alpha.0 release (#735)
Browse files Browse the repository at this point in the history 
Signed-off-by: Anish Ramasekar <[email protected]>
  • Loading branch information
@aramase
aramase committed Feb 7, 2023
1 parent e471d98 commit 0f2c75e
Show file tree
Hide file tree
Showing 5 changed files with 47 additions and 44 deletions.
2 changes: 1 addition & 1 deletion docs/book/src/known-issues.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ az account get-access-token --resource-type=ms-graph
To bypass this policy:
- `az login` with a user account on a supported system - Windows or MacOS, and make the device compliant.
- `az login --service-principal` with a service principal which does not have the above compilance check.
- `az login --service-principal` with a service principal which does not have the above compliance check.
In the case of service principal, you will have to grant the `Application.ReadWrite.All` API permission:
Expand Down
4 changes: 2 additions & 2 deletions docs/book/src/quick-start.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -169,7 +169,7 @@ metadata:
annotations:
azure.workload.identity/client-id: ${APPLICATION_CLIENT_ID:-$USER_ASSIGNED_IDENTITY_CLIENT_ID}
labels:
azure.workload.identity/use: "true"
azure.workload.identity/use: "true" # if you're using azure-workload-identity v1.0.0+, this label is not required.
name: ${SERVICE_ACCOUNT_NAME}
namespace: ${SERVICE_ACCOUNT_NAMESPACE}
EOF
Expand Down Expand Up @@ -330,7 +330,7 @@ Namespace: default
Priority: 0
Node: k8s-agentpool1-38097163-vmss000002/10.240.0.34
Start Time: Wed, 13 Oct 2021 15:49:25 -0700
Labels: <none>
Labels: azure.workload.identity/use=true
Annotations: <none>
Status: Running
IP: 10.240.0.55
Expand Down
4 changes: 2 additions & 2 deletions docs/book/src/topics/self-managed-clusters/service-account-key-rotation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -139,14 +139,14 @@ kind: ServiceAccount
metadata:
annotations:
azure.workload.identity/client-id: dummy
labels:
azure.workload.identity/use: "true"
name: workload-identity-sa
---
apiVersion: v1
kind: Pod
metadata:
name: dummy-pod
labels:
azure.workload.identity/use: "true"
spec:
serviceAccountName: workload-identity-sa
containers:
Expand Down
39 changes: 20 additions & 19 deletions docs/book/src/topics/service-account-labels-and-annotations.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,37 +4,38 @@

The following is a list of available labels and annotations that can be used to configure the behavior when exchanging the service account token for an AAD access token:

## Service Account
## Pod

### Labels

| Label | Description | Recommended value | Required? |
| ----------------------------- | ------------------------------------------------------------------- | ----------------- | --------- |
| `azure.workload.identity/use` | Represents the service account is to be used for workload identity. | `true` | ✓ |
| Label | Description | Recommended value | Required? |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | --------- |
| `azure.workload.identity/use` | This label is **required** in the pod template spec. Only pods with this label will be mutated by the azure-workload-identity mutating admission webhook to inject the Azure specific environment variables and the projected service account token volume. | `true` | ✓ |

### Annotations

| Annotation | Description | Default |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `azure.workload.identity/client-id` | Represents the AAD application client ID to be used with the pod. | |
| `azure.workload.identity/tenant-id` | Represents the Azure tenant ID where the AAD application is registered. | `AZURE_TENANT_ID` environment variable extracted from [`azure-wi-webhook-config`][1] ConfigMap |
| `azure.workload.identity/service-account-token-expiration` | Represents the `expirationSeconds` field for the projected service account token. It is an optional field that the user might want to configure this to prevent any downtime caused by errors during service account token refresh. Kubernetes service account token expiry will not be correlated with AAD tokens. AAD tokens will expire in 24 hours after they are issued. | `3600` (acceptable range: `3600 - 86400`) |
| Annotation | Description | Default |
| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| `azure.workload.identity/service-account-token-expiration` | **(Takes precedence if the service account is also annotated)** Represents the `expirationSeconds` field for the projected service account token. It is an optional field that the user might want to configure this to prevent any downtime caused by errors during service account token refresh. Kubernetes service account token expiry will not be correlated with AAD tokens. AAD tokens will expire in 24 hours after they are issued. | `3600` (acceptable range: `3600 - 86400`) |
| `azure.workload.identity/skip-containers` | Represents a semi-colon-separated list of containers (e.g. `container1;container2`) to skip adding projected service account token volume. By default, the projected service account token volume will be added to all containers. | |
| `azure.workload.identity/inject-proxy-sidecar` | Injects a proxy init container and proxy sidecar into the pod. The proxy sidecar is used to intercept token requests to IMDS and acquire an AAD token on behalf of the user with federated identity credential. | `true` |
| `azure.workload.identity/proxy-sidecar-port` | Represents the port of the proxy sidecar. | `8080` |

## Pod

## Service Account

### Labels

| Label | Description | Recommended value | Required? |
| ----------------------------- | ------------------------------------------------------- | ----------------- | --------- |
| `azure.workload.identity/use` | Represents the pod is to be used for workload identity. | `true` | ✓ |
| Label | Description | Recommended value | Required? |
| ----------------------------- | ------------------------------------------------------------------- | ----------------- | --------------------------------------------------------------------------------- |
| `azure.workload.identity/use` | Represents the service account is to be used for workload identity. | `true` | **This label is only required if using azure-workload-identity version < v1.0.0** |

### Annotations

| Annotation | Description | Default |
| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| `azure.workload.identity/service-account-token-expiration` | **(Takes precedence if the service account is also annotated)** Represents the `expirationSeconds` field for the projected service account token. It is an optional field that the user might want to configure this to prevent any downtime caused by errors during service account token refresh. Kubernetes service account token expiry will not be correlated with AAD tokens. AAD tokens will expire in 24 hours after they are issued. | `3600` (acceptable range: `3600 - 86400`) |
| `azure.workload.identity/skip-containers` | Represents a semi-colon-separated list of containers (e.g. `container1;container2`) to skip adding projected service account token volume. By default, the projected service account token volume will be added to all containers if the service account is labeled with `azure.workload.identity/use: true`. | |
| `azure.workload.identity/inject-proxy-sidecar` | Injects a proxy init container and proxy sidecar into the pod. The proxy sidecar is used to intercept token requests to IMDS and acquire an AAD token on behalf of the user with federated identity credential. | `true` |
| `azure.workload.identity/proxy-sidecar-port` | Represents the port of the proxy sidecar. | `8080` |
| Annotation | Description | Default |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `azure.workload.identity/client-id` | Represents the AAD application client ID to be used with the pod. | |
| `azure.workload.identity/tenant-id` | Represents the Azure tenant ID where the AAD application is registered. | `AZURE_TENANT_ID` environment variable extracted from [`azure-wi-webhook-config`][1] ConfigMap |
| `azure.workload.identity/service-account-token-expiration` | Represents the `expirationSeconds` field for the projected service account token. It is an optional field that the user might want to configure this to prevent any downtime caused by errors during service account token refresh. Kubernetes service account token expiry will not be correlated with AAD tokens. AAD tokens will expire in 24 hours after they are issued. | `3600` (acceptable range: `3600 - 86400`) |

[1]: https://github.com/Azure/azure-workload-identity/blob/40b3842dc49784bb014ad5d8b02cf6c959244196/deploy/azure-wi-webhook.yaml#L101-L110
42 changes: 22 additions & 20 deletions docs/book/src/troubleshooting.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,26 +26,6 @@ kubectl logs -n azure-workload-identity-system -l app=workload-identity-webhook

> It is always a good idea to include relevant logs from the webhook when opening a new [issue][1]
## Ensure the service account is labeled with `azure.workload.identity/use=true`

`azure.workload.identity/use=true` label on the service account represents the service account is to be used for workload identity. If the service account is not labeled, the mutating admission webhook will not inject the required environment variables or volume mounts into the workload pod.

Run the following command to check if the service account is labeled:

```bash
kubectl get sa workload-identity-sa -n oidc -o jsonpath='{.metadata.labels.azure\.workload\.identity/use}'
```

<details>
<summary>Output</summary>

```bash
kubectl get sa workload-identity-sa -n oidc -o jsonpath='{.metadata.labels.azure\.workload\.identity/use}'
true
```

</details>

## AADSTS70021: No matching federated identity record found for presented assertion.

```
Expand Down Expand Up @@ -90,3 +70,25 @@ export SERVICE_ACCOUNT_ISSUER="<your service account issuer url>" # see section
curl ${SERVICE_ACCOUNT_ISSUER}/.well-known/openid-configuration
curl ${SERVICE_ACCOUNT_ISSUER}/openid/v1/jwks
```

## Workload pod doesn't have the Azure specific environment variables and projected service account token volume after upgrading to v1.0.0

As of v1.0.0 release, the azure-workload-identity mutating admission webhook is defaulting to using `failurePolicy: Fail` instead of `Ignore`. With this change, we have added an [object selector](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#matching-requests-objectselector) in the configuration to only intercept and mutate pods that have the `azure.workload.identity/use: "true"` label. This change reduces the latency impact of the webhook and prevents workload pods that require the injected environment variables and projected service account token volume from starting in an unexpected state. Refer to [issue](https://github.com/Azure/azure-workload-identity/issues/601) for more details.

If you are upgrading from a previous version of the azure-workload-identity, you will need to add the `azure.workload.identity/use: "true"` label to your workload pods to ensure that the mutating admission webhook is able to inject the required environment variables and projected service account token volume.

Run the following command to check if the workload pod is labeled:

```bash
kubectl get pod quick-start -n oidc -o jsonpath='{.metadata.labels.azure\.workload\.identity/use}'
```

<details>
<summary>Output</summary>

```bash
kubectl get pod quick-start -n oidc -o jsonpath='{.metadata.labels.azure\.workload\.identity/use}'
true
```

</details>

0 comments on commit 0f2c75e

Please sign in to comment.