Kubernetes Secrets carry a `type` field with values such as `Opaque`, `kubernetes.io/tls` and `kubernetes.io/dockerconfigjson`. What does the type actually change, and can you change it later?

## Type as a contract, not a mechanism Every Secret has a `type` string. It is metadata that declares the *shape* of the payload. Two parties act on it: the API server, which validates required keys for built-in types at admission, and consumers, which use it to decide whether a given Secret is the kind of thing they need. Crucially, the type changes nothing about how the object is stored, encoded, encrypted or delivered to Pods. A `kubernetes.io/tls` Secret is base64 in `data` and plaintext in etcd exactly like an `Opaque` one. Candidates who claim TLS-typed Secrets are "handled more securely" are guessing. ## The built-in types **`Opaque`** — the default when you omit the field. Arbitrary keys, no validation whatsoever. Most application credentials live here. **`kubernetes.io/tls`** — requires `tls.crt` and `tls.key`; `ca.crt` is a conventional optional extra. This is the type Ingress controllers, Gateway API implementations and service meshes look for when a manifest references a TLS Secret, and it is what cert-manager writes. Getting the type wrong here is the classic "my Ingress serves the default certificate" bug: the controller looks for a TLS-typed Secret with those exact key names and quietly falls back when it does not find one. **`kubernetes.io/dockerconfigjson`** — requires the key `.dockerconfigjson` (note the leading dot), whose value is a Docker-style config JSON containing registry hosts and auths. This is the type `imagePullSecrets` consumes; an `Opaque` Secret holding the same JSON will not work. There is a legacy `kubernetes.io/dockercfg` type using the older `.dockercfg` format. **`kubernetes.io/basic-auth`** — `username` and `password`. Used by tooling that wants a conventional shape (some Ingress auth annotations, Argo CD repository credentials). **`kubernetes.io/ssh-auth`** — requires `ssh-privatekey`. Used for git-over-SSH credentials by GitOps controllers and init containers. **`kubernetes.io/service-account-token`** — annotated with `kubernetes.io/service-account.name`; the token controller fills in `token`, `ca.crt` and `namespace`. Modern clusters mount short-lived projected tokens into Pods automatically instead, and these long-lived Secrets are created only on demand — they are the right answer when something outside the cluster needs a token, and the wrong answer for in-cluster workloads. **`bootstrap.kubernetes.io/token`** — kubeadm node-join tokens, living in `kube-system`. You can also invent your own type string, conventionally namespaced like `example.com/my-type`. Custom types get no API-server validation; they exist so *your* controller can filter (`kubectl get secrets --field-selector type=example.com/my-type`) and so humans can tell at a glance what a Secret is for. ## Validation you get for free For the built-in types the API server enforces required keys at write time. Create a `kubernetes.io/tls` Secret with `cert.pem` and `key.pem` instead of `tls.crt`/`tls.key` and the request is rejected outright. This is genuinely useful: it converts a silent runtime misconfiguration (an Ingress serving a fallback certificate, an image pull failing with an unhelpful 401) into a loud failure at apply time. It is also the reason you should type your Secrets properly rather than defaulting everything to `Opaque`. ## Immutability of the type field `type` cannot be changed after creation — the API server rejects updates to it. If you created a registry credential as `Opaque` and pulls are failing, you must delete and recreate it with the right type. Note this is a separate rule from the `immutable: true` flag; the type is fixed on every Secret, immutable or not. ## The kubectl helpers `kubectl create secret` has subcommands per type, and using them is the easy way to get keys and encoding right: - `kubectl create secret generic` → `Opaque` (with `--from-literal`, `--from-file`, `--from-env-file`) - `kubectl create secret tls` → `kubernetes.io/tls` - `kubectl create secret docker-registry` → `kubernetes.io/dockerconfigjson` Each handles the base64 encoding and, for docker-registry, assembles the config JSON correctly — including the base64 `auth` field that people typically get wrong by hand. ## How to use the type in review When reviewing a manifest, the type tells you what the Secret is for without reading its data — which matters because you often cannot read its data. `type: kubernetes.io/tls` in a namespace with no Ingress is worth a question; `Opaque` where a controller expects a specific type is a latent bug. Treat it as documentation the API server enforces.