# Install an add-on

Install metrics-server, Traefik, cert-manager or external-dns on a cluster, change its version or options, or remove it.

Replace _my-cluster_ with your cluster's name or id, and _example.com_ with a hosted zone of your
organization in Deutsche Cloud DNS.

Deutsche Cloud applies an add-on's objects in the cluster and puts them back if they are changed there.
Upgrades are never automatic: you change the version when you are ready.

| Add-on           | Versions       | What it does                                                                                                                                  | Options                                                                                           |
| ---------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `metrics-server` | 0.9.0, 0.8.1   | `kubectl top` and the HorizontalPodAutoscaler. Installed on every new cluster unless the create lists other add-ons or `[]`.                  | none                                                                                              |
| `traefik`        | 3.7.17, 3.7.16 | Ingress controller for Ingress, Gateway API and IngressRoute behind one load balancer; also serves Ingresses of class `nginx`.                | `replicas` (2), `proxyProtocol` (true), `loadBalancerType` (`lb11`), `defaultIngressClass` (true) |
| `cert-manager`   | 1.21.3, 1.20.5 | Certificates from Let's Encrypt; ClusterIssuers `letsencrypt` and `letsencrypt-staging`. DNS-01 in the listed zones, HTTP-01 through Traefik. | `zones`, `email`                                                                                  |
| `external-dns`   | 0.23.0, 0.22.0 | Records in Deutsche Cloud DNS for LoadBalancer Services and Ingresses; HTTPRoutes too when `sources` includes `gateway-httproute`.               | `zones` (required), `policy` (`sync`), `sources` (`service`, `ingress`)                           |

The DNS add-ons hold no credential: they prove themselves with their service-account tokens.
external-dns may change A, AAAA, CNAME and TXT records in its zones; cert-manager's solver only
`_acme-challenge` TXT records.

## Prerequisites

- Permission for `eks:CreateAddon` (to change: `eks:UpdateAddon`; to remove: `eks:DeleteAddon`).
- For `external-dns`, or `cert-manager` with zones, also `dns:ChangeRecords` on every zone listed.
- In the console, also `eks:DescribeCluster` to open the cluster, `eks:ListAddons` to see the
  add-ons, and `eks:DescribeAddonVersions`: without it the console has no versions to offer, so
  **Install an add-on** offers nothing and **Change** lists no version.

## Install an add-on

**Console**
1. Open **Kubernetes**, open the cluster, then choose **Add-ons**.
2. Under **Install an add-on**, choose the add-on.
3. Fill in its options, if it has any.
4. Choose **Install**.

The console installs the newest version for the cluster's Kubernetes minor.

**CLI**
```sh
dcloud eks addon-versions list --kubernetes-version 1.36
dcloud eks addons create my-cluster --name external-dns --config 'zones=["example.com"]'
```

**API**
```http
POST /eks/api/clusters/my-cluster/addons
{ "name": "external-dns", "config": { "zones": ["example.com"] } }
```

**Terraform**
```hcl
resource "dcloud_eks_addon" "external_dns" {
  cluster_id = dcloud_eks_cluster.main.id
  name       = "external-dns"
  config     = jsonencode({ zones = ["example.com"] })
}
```

The add-on is `creating` until the cluster has applied it and its workloads have all their replicas
ready, then `active`. If it is not applied, or not ready, after 10 minutes, it goes `degraded` with
the reason (a change that does not apply goes `update_failed`).

## Change or remove an add-on

- **Change:** on the **Add-ons** tab, choose **Change**, pick the **Version** and options, and choose
  **Apply**; or `dcloud eks addons update my-cluster traefik --version 3.7.17`. New options
  replace the old ones as a whole.
- **Remove:** choose **Remove** and confirm; or `dcloud eks addons delete my-cluster traefik`.
  Its workloads and the objects Deutsche Cloud made for it are deleted; its CRDs and your resources of
  them (Certificates, IngressRoutes) stay.

A cluster upgrade is refused while an add-on's version does not support the next minor; the
cluster's `upgradeBlockers` names the version to update to first.

## Refusals

- `400` for a version not offered or options the add-on does not take.
- `404` "No hosted zone _example.com_ in this organization (create it in DNS first)".
- `403` without `dns:ChangeRecords` on a zone the options list.
- `409` "The cluster already has _external-dns_", "The cluster is being deleted", "The add-on is
  being removed" (on a change), a version that does not support the cluster's minor, a control
  plane built before managed add-ons, or the add-ons quota is full.

## Related

- [Expose a Service](expose-a-service.md)
- `eks.addons.create` · `dcloud eks addons create` · `dcloud_eks_addon`
