API server flags and configuration — secure-port, audit, encryption

The kube-apiserver has dozens of flags; production operators only need to know a small subset: those that control security (TLS, audit, encryption), runtime behaviour (rate limits, profiling), and integration (API aggregator, etcd connection). This lesson walks the flags that matter most, where they live in kubeadm, and the discipline of changing them.

Where the flags live

For a kubeadm-managed cluster:

sudo cat /etc/kubernetes/manifests/kube-apiserver.yaml

The static pod manifest contains the flags as command-line arguments:

spec:
  containers:
  - name: kube-apiserver
    image: registry.k8s.io/kube-apiserver:v1.34.x
    command:
    - kube-apiserver
    - --advertise-address=10.0.1.10
    - --allow-privileged=true
    - --authorization-mode=Node,RBAC
    - --client-ca-file=/etc/kubernetes/pki/ca.crt
    - --enable-admission-plugins=NodeRestriction
    - --etcd-cafile=/etc/kubernetes/pki/etcd/ca.crt
    - --etcd-servers=https://127.0.0.1:2379
    - --service-cluster-ip-range=10.96.0.0/16
    - --service-account-key-file=/etc/kubernetes/pki/sa.key
    - --service-account-signing-key-file=/etc/kubernetes/pki/sa.key
    - --service-account-issuer=https://kubernetes.default.svc.cluster.local
    - --tls-cert-file=/etc/kubernetes/pki/apiserver.crt
    - --tls-private-key-file=/etc/kubernetes/pki/apiserver.key

The flags every operator must understand

Authentication and authorisation

Network and TLS

etcd

The etcd URL list is typically three entries (https://10.0.1.10:2379,https://10.0.1.11:2379,...).

Service accounts

The --service-account-issuer and signing key are central to Kubernetes’ projected ServiceAccount tokens (PART LX — Service Accounts).

Audit logging

--audit-policy-file=/etc/kubernetes/audit-policy.yaml
--audit-log-path=/var/log/kubernetes/audit/audit.log
--audit-log-maxage=30
--audit-log-maxbackup=10
--audit-log-maxsize=100

The audit policy file is a YAML configuration:

apiVersion: audit.k8s.io/v1
kind: Policy
rules:
- level: Metadata
  namespaces: ["kube-system"]
  resources:
  - group: ""
    resources: ["secrets", "configmaps"]
- level: RequestResponse
  verbs: ["create", "delete", "update"]

The policy’s rules determine what gets logged.

Encryption at rest

--encryption-provider-config=/etc/kubernetes/encryption-config.yaml

The configuration file (Part XXI) controls Secret encryption. The API server encrypts configured resources on write; decryption happens on read.

Rate limiting and profiling

--enable-profiling=true exposes /debug/pprof for performance investigation; production typically enables this on a control-plane host with restricted access.

$ crictl exec <api-server-pod-id> /server --print-flags | grep -E '(secure-port|etcd-servers|audit)' | head

...

Editing the manifest safely

To add a flag to the API server:

1. Capture the current manifest:

sudo cp /etc/kubernetes/manifests/kube-apiserver.yaml \
        /backup/kube-apiserver.yaml.$(date +%Y%m%d-%H%M)

2. Edit the manifest:

sudo vi /etc/kubernetes/manifests/kube-apiserver.yaml
# Add the new flag, e.g., `--enable-profiling=true`

3. The kubelet observes the change and restarts the pod:

sleep 10
crictl pods | grep apiserver
# Observe: old pod stopped, new pod starting

4. Verify the flag took effect:

# The id of the new pod, from the `crictl pods` output above:
API_SERVER_POD_ID=8f3c1a9d4e7b2

crictl exec "$API_SERVER_POD_ID" /server --print-flags | grep profiling
# Or kubectl logs on the API server pod

Common flag operations

Enable profiling

sudo vi /etc/kubernetes/manifests/kube-apiserver.yaml
# Add:
#   - --enable-profiling=true
#   - --profiling-bind-address=127.0.0.1
# (or expose via port forward to localhost)

Configure audit logging

sudo vi /etc/kubernetes/audit-policy.yaml
# ... write the policy

sudo vi /etc/kubernetes/manifests/kube-apiserver.yaml
# Add:
#   - --audit-policy-file=/etc/kubernetes/audit-policy.yaml
#   - --audit-log-path=/var/log/kubernetes/audit/audit.log
#   - --audit-log-maxage=30
#   - --audit-log-maxbackup=10
#   - --audit-log-maxsize=100

The audit log directory must exist and be writable by the API server process.

Configure encryption at rest

sudo vi /etc/kubernetes/encryption-config.yaml
# ... write the EncryptionConfiguration

sudo vi /etc/kubernetes/manifests/kube-apiserver.yaml
# Add:
#   - --encryption-provider-config=/etc/kubernetes/encryption-config.yaml

After the restart, re-write all Secrets:

kubectl get secrets -A -o json | kubectl replace -f -

The flag validation

Some flags have specific format requirements:

• --tls-cert-file must point to a PEM file.
• --etcd-servers must be HTTPS URLs.
• --service-account-issuer must be a URL.
• --authorization-mode must be a comma-separated list of valid modes.

A misconfigured flag prevents the API server from starting; the kubelet logs the failure.

$ crictl logs <api-server-pod-id> | tail -30

Error: invalid value "AlwaysDeny" for flag -authorization-mode ... "Mode ["AlwaysDeny"] not in [Node,RBAC,...]"

API server metrics

The API server exposes metrics for SLO monitoring:

# API server requests by verb and resource
apiserver_request_total{verb="create",resource="pods",code="200"}

# Latency by step
apiserver_admission_step_advertised_duration_seconds{operation="mutating_webhook"}

# Watch totals
apiserver_watch_total{resource="pods"}

The metrics surface is the production discipline: every production API server should have these metrics flowing to Prometheus.

The reload-capable flags

Some flags support hot reload without restart:

• --audit-policy-file: file watches; the API server reloads on changes.

Most other flags require a pod restart.

Quiz

Production discipline

• Touch the manifest rarely. Each flag change is a restart; changes accumulate risk.
• Capture before editing. cp the manifest aside; the rollback is a mv back.
• Verify after restart. The new flag should appear in crictl logs or kubectl logs on the new pod.
• Audit logging is mandatory. The audit log is the compliance evidence; without it, the cluster fails PCI / HIPAA / SOC 2 audits.
• Encryption at rest is mandatory for production credentials. AES-GCM at minimum; KMS for high-value secrets.

API server flags are the levers for cluster security and behaviour. Change one at a time; verify each.