# atmos azure aks update-kubeconfig

Download the `kubeconfig` for an AKS cluster and save it to a file, using the Azure Go SDK. No `az` CLI or `kubelogin` binary is required.

## Usage

```shell
atmos azure aks update-kubeconfig [flags]
```

This command supports two execution modes:

1. **Integration mode**: Use a named integration from `auth.integrations` to authenticate via the Atmos auth system and generate kubeconfig using the Go SDK.

   ```shell
   atmos azure aks update-kubeconfig --integration=dev/aks
   ```

2. **Identity mode**: Use an Atmos identity directly with explicit cluster parameters.

   ```shell
   atmos azure aks update-kubeconfig --cluster-name=<cluster_name> --resource-group=<resource_group> --identity=<identity_name>
   ```

:::tip
Run `atmos azure aks update-kubeconfig --help` to see all the available options
:::

## Examples

```shell
# Using a named integration
atmos azure aks update-kubeconfig --integration=dev/aks

# Using an identity with explicit parameters
atmos azure aks update-kubeconfig --cluster-name=dev-cluster --resource-group=dev-rg --identity=azure-dev

# Overriding the subscription and kubeconfig path
atmos azure aks update-kubeconfig --integration=dev/aks --subscription-id=00000000-0000-0000-0000-000000000000 --kubeconfig=~/.kube/config

# Setting a custom context alias
atmos azure aks update-kubeconfig --integration=dev/aks --alias=dev-aks
```

## Arguments

- **n/a**
  No positional arguments.

## Flags

- **`--integration` (optional)**

  Name of a configured integration from `auth.integrations` (must be `kind: azure/aks`). When specified, Atmos authenticates the integration's linked identity and uses the Go SDK to describe the cluster and generate kubeconfig.
- **`--cluster-name` (optional)**
  The name of the AKS cluster. Required (with 
  `--resource-group`
   and 
  `--identity`
  ) when not using 
  `--integration`
  .
- **`--resource-group` (optional)**
  The Azure resource group containing the cluster. Required (with 
  `--cluster-name`
   and 
  `--identity`
  ) when not using 
  `--integration`
  .
- **`--subscription-id` (optional)**
  Azure subscription ID. Falls back to the authenticated identity's subscription when omitted.
- **`--identity` (alias `-i`)**

  Atmos identity to authenticate with. When used with `--cluster-name` and `--resource-group`, Atmos authenticates via the auth system and uses the Go SDK directly.
- **`--kubeconfig` (optional)**

  `kubeconfig` filename to append with the configuration. Defaults to the XDG-compliant path (`~/.config/atmos/kube/config`). Also bound to the `KUBECONFIG` and `ATMOS_KUBECONFIG` environment variables. When used with `--integration`, this overrides the integration's configured `spec.cluster.kubeconfig.path`. A leading `~` and environment variables (`$VAR`, `${VAR}`) in the value are expanded.
- **`--alias` (optional)**
  Alias for the cluster context name. Defaults to the cluster's ARM resource ID. When used with 
  `--integration`
  , this overrides the integration's configured 
  `spec.cluster.alias`
  .

:::note Overrides and path expansion
`--kubeconfig` and `--alias` are honored on both execution modes. With `--integration`, they override the integration's configured `spec.cluster.kubeconfig.path` and `spec.cluster.alias` for that run - useful for writing a per-cluster kubeconfig without editing the committed config.

Both the `--kubeconfig` flag and the integration's `spec.cluster.kubeconfig.path` are expanded before use: a leading `~` (or `~/`) resolves to the current user's home directory, and environment variables (`$HOME`, `${HOME}`) are substituted. This keeps a committed, multi-developer integration config portable - for example, `path: "${HOME}/.config/atmos/kube/qa"` writes to each user's own home directory.
:::

## Configuration

### Integration Mode

AKS integrations are configured in `atmos.yaml` under `auth.integrations`:

```yaml
auth:
  providers:
    azure-device-code:
      kind: azure/device-code
      spec:
        tenant_id: 00000000-0000-0000-0000-000000000000

  identities:
    azure-dev:
      kind: azure/subscription
      via:
        provider: azure-device-code
      principal:
        subscription_id: 11111111-1111-1111-1111-111111111111

  integrations:
    dev/aks:
      kind: azure/aks
      via:
        identity: azure-dev
      spec:
        cluster:
          name: dev-cluster
          resource_group: dev-rg
          alias: dev-aks
```

```shell
atmos azure aks update-kubeconfig --integration=dev/aks
```

## How It Works

Unlike `az aks get-credentials`, this command never shells out to `az` or requires the `kubelogin` binary. It:

1. Calls the Azure Resource Manager `ManagedClusters.Get` API for the cluster's ARM resource ID.
2. Calls `ManagedClusters.ListClusterUserCredentials` (format `exec`) to obtain the cluster's server endpoint, CA certificate, and the AAD server application ID the cluster expects tokens to be scoped to.
3. Writes a kubeconfig entry whose exec-credential plugin invokes `atmos azure aks token` instead of `kubelogin`.

Only AAD-integrated clusters are supported — clusters using local Kubernetes accounts (no AAD integration) are rejected with a clear error.

## See Also

- [Azure AKS Token Command](/cli/commands/azure/azure-aks-token) — Generate AKS bearer tokens for kubectl
- [Auth Login Command](/cli/commands/auth/login) — Authenticate with identities (triggers auto-provisioned integrations)