Integrate Kubernetes Engine with Secrets Manager

Install External Secrets Operator (ESO) on a KakaoCloud Kubernetes Engine cluster and verify the basic integration with Secrets Manager.

Basic information

• Estimated time: About 30 minutes
• Prerequisites
  • IAM access keys
  • Prepare to use the API
  • Prepare the cluster and installation environment
  • Create a Secrets Manager secret

Caution

• The KakaoCloud Secrets Manager provider is read-only and does not support creating, modifying, or deleting Secrets Manager secrets. See Scope and limitations in the service guide.
• You must have permission to read the target secret value in the project for which the access key was issued. See Secrets Manager and KMS roles for the required permissions.

Scenario overview

This tutorial walks you through installing External Secrets Operator (ESO) on a Kubernetes Engine cluster and synchronizing a KakaoCloud Secrets Manager secret to a Kubernetes Secret.
ESO reads secret values from Secrets Manager, creates Kubernetes Secrets, and applies changes at the configured interval.

The main steps are:

• Install ESO
• Configure Secrets Manager credentials
• Create a SecretStore and ExternalSecret
• Verify Kubernetes Secret synchronization

See Integration architecture in the service guide for the roles of each resource.

Deployment information

This tutorial installs version 2.10.0-kc.1 of the oci://ghcr.io/kakaoenterprise/charts/external-secrets chart using Helm 3 and kubectl. See the service guide's Deployment information for the container image and base ESO version, and Version information for versioning conventions.

Before you start

Prepare a Kubernetes cluster and a Secrets Manager secret, and check the network requirements before starting.

Prepare cluster and installation environment

You need a Kubernetes cluster that meets all of the following requirements:

• At least one running amd64 (x86_64) worker node in Ready state
• Local kubectl access to the cluster
• Helm 3 installed
• A kubeconfig configured so that kubectl and helm connect to the target cluster
• External HTTPS communication allowed from worker nodes or ESO pods

If you do not have a cluster, follow Create and manage clusters. Prepare local access by following Configure kubectl access.

Caution

The KakaoCloud Helm chart requires Kubernetes 1.33 or later. Installation is restricted on earlier cluster versions.

Create Secrets Manager secret

Follow the Create a secret guide to prepare a practice secret and note its ID. See Secrets Manager and KMS roles for the permissions required to create secrets and read their values.

If you use per-secret access control, include the IAM principal used by ESO in the allowed targets.

Caution

• ExternalSecret uses the secret ID, not the secret name. Check the target secret ID in the console.

Check network communication

The following external and internal cluster communication paths are required for ESO installation and secret synchronization.

Source	Destination	Port	Purpose
Installation environment or worker node	ghcr.io, pkg-containers.githubusercontent.com	TCP 443	Download Helm charts and container images
ESO controller pod	iam.kakaocloud.com	TCP 443	Issue IAM authentication tokens
ESO controller pod	secrets-manager-service.kr-central-2.kakaocloud.com	TCP 443	Retrieve secret values
Kubernetes API server	ESO webhook	Depends on webhook settings	Validate SecretStore, ClusterSecretStore, and ExternalSecret admission (see webhook settings)

Check network communication paths

The IAM and Secrets Manager addresses above are public endpoints. When using a private endpoint, replace the destination for that service with its actual endpoint address. See Use private endpoints in the service guide.

Accessing GHCR or public endpoints from a private subnet may require an external communication path such as NAT. In environments using firewalls, security groups, or NetworkPolicy, allow the communication paths you use.

Get started

Follow the steps below to install ESO and integrate it with Secrets Manager.

Step 1. Connect to cluster and check tools

Check that the current kubectl context points to the target cluster.

Check cluster context and tools

kubectl config current-context
kubectl get nodes
helm version

The setup is ready when:

• The target cluster context is displayed
• Worker nodes are in Ready state
• The Helm 3 version is displayed

Step 2. Inspect Helm chart

Inspect the Helm chart published to GHCR.

Inspect the Helm chart

helm show chart \
  oci://ghcr.io/kakaoenterprise/charts/external-secrets \
  --version 2.10.0-kc.1

Proceed with installation when the chart information is displayed successfully.

Step 3. Install ESO with Helm

Use the following command on Kubernetes 1.34 or later. On Kubernetes 1.33, add the options in the note below.

Install ESO

helm upgrade --install external-secrets \
  oci://ghcr.io/kakaoenterprise/charts/external-secrets \
  --version 2.10.0-kc.1 \
  --namespace external-secrets \
  --create-namespace \
  --set installCRDs=true \
  --wait \
  --timeout=5m

Webhook settings by Kubernetes version

• On Kubernetes 1.33, add --set webhook.hostNetwork=true and --set webhook.port=9443 to the command above so that the API server can communicate with the admission webhook. Port 9443 avoids a conflict between ESO's default webhook port 10250 and the worker node's Kubelet port when using the host network.
• On Kubernetes 1.34 or later, the API server communicates with the webhook through Konnectivity, so the options above are not required.

The published ESO image supports the amd64 architecture. If the cluster also contains nodes with other architectures, save the following as eso-node-selector.yaml and add -f eso-node-selector.yaml to the installation command above. This schedules the controller, webhook, and cert-controller on amd64 nodes.

eso-node-selector.yaml

global:
  nodeSelector:
    kubernetes.io/arch: amd64

Step 4. Check installation status

Check the Helm release status.

Check Helm release

helm list --namespace external-secrets

Check the pods and Deployment.

Check pods and Deployment

kubectl get pods -n external-secrets
kubectl get deployment -n external-secrets

The controller, webhook, and cert-controller pods must all be Running and Ready. Also check that the CRDs were created.

Check CRDs

kubectl get crd \
  externalsecrets.external-secrets.io \
  secretstores.external-secrets.io \
  clustersecretstores.external-secrets.io

Step 5. Create application namespace

Prepare a namespace for the SecretStore, ExternalSecret, and synchronized Kubernetes Secret.

Create a namespace

kubectl create namespace eso-demo

Skip this step if eso-demo already exists. To use another namespace, replace eso-demo with that name in the commands and YAML below.

Step 6. Create IAM credentials Secret

Create a Kubernetes Secret containing the IAM access key ID and secret access key. Enter both values in the input fields below the code before copying and running the command. If the fields are left empty, the literal ${...} strings are stored instead of credentials.

Create a credentials Secret

kubectl -n eso-demo create secret generic kakaocloud-credentials \
  --from-literal=accessKeyID='${IAM_ACCESS_KEY_ID}' \
  --from-literal=secretAccessKey='${SECRET_ACCESS_KEY}'

Variable	Description
IAM_ACCESS_KEY_ID🖌︎	IAM access key ID
SECRET_ACCESS_KEY🖌︎	Secret access key

Check the result.

Check the credentials Secret

kubectl get secret kakaocloud-credentials -n eso-demo

Caution

The IAM access key you enter may be saved in the shell command history.

Step 7. Create SecretStore

SecretStore defines the KakaoCloud IAM and Secrets Manager endpoints and the location of the credentials Secret. Write the following to secret-store.yaml.

secret-store.yaml

apiVersion: external-secrets.io/v1
kind: SecretStore
metadata:
  name: kakaocloud-secret-store
  namespace: eso-demo
spec:
  provider:
    kakaocloud:
      secretsManagerEndpoint: https://secrets-manager-service.kr-central-2.kakaocloud.com
      auth:
        iamEndpoint: https://iam.kakaocloud.com
        secretRef:
          accessKeyID:
            name: kakaocloud-credentials
            key: accessKeyID
          secretAccessKey:
            name: kakaocloud-credentials
            key: secretAccessKey

Enter only the HTTPS base URLs in secretsManagerEndpoint and auth.iamEndpoint; do not add API paths, query strings, or user information.

Apply the SecretStore and wait until it is Ready.

Apply SecretStore

kubectl apply -f secret-store.yaml

kubectl wait \
  --for=condition=Ready \
  secretstore/kakaocloud-secret-store \
  -n eso-demo \
  --timeout=60s

Check its status.

Check SecretStore status

kubectl get secretstore kakaocloud-secret-store -n eso-demo

The normal status displays READY=True. If it is READY=False, inspect the details.

Check SecretStore details

kubectl describe secretstore kakaocloud-secret-store -n eso-demo

Step 8. Create ExternalSecret

ExternalSecret defines the Secrets Manager secret ID to retrieve and the Kubernetes Secret to create. Write the following to external-secret.yaml.

external-secret.yaml

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: kakaocloud-external-secret
  namespace: eso-demo
spec:
  refreshPolicy: Periodic
  refreshInterval: 1h0m0s
  secretStoreRef:
    name: kakaocloud-secret-store
    kind: SecretStore
  target:
    name: kakaocloud-synced-secret
    creationPolicy: Owner
  data:
    - secretKey: password
      remoteRef:
        key: ${KAKAOCLOUD_SECRET_ID}
        # property: password

Variable	Description
KAKAOCLOUD_SECRET_ID🖌︎	Secrets Manager secret ID

This example stores the entire Secrets Manager secret value in the password key of a Kubernetes Secret. If the source value is a JSON object and you want only its password field, uncomment property: password.

Enter the actual Secrets Manager secret ID in the input field below the code and save the generated YAML. Apply the manifest and wait until it is Ready.

Apply ExternalSecret

kubectl apply -f external-secret.yaml

kubectl wait \
  --for=condition=Ready \
  externalsecret/kakaocloud-external-secret \
  -n eso-demo \
  --timeout=60s

Step 9. Verify synchronization

Check the ExternalSecret status.

Check ExternalSecret status

kubectl get externalsecret kakaocloud-external-secret -n eso-demo

When synchronization succeeds, STATUS is SecretSynced and READY is True.

Example output (some columns omitted)

NAME                          STORE                      REFRESH INTERVAL   STATUS         READY
kakaocloud-external-secret    kakaocloud-secret-store    1h0m0s             SecretSynced   True

Inspect detailed status and events.

Check ExternalSecret details

kubectl describe externalsecret kakaocloud-external-secret -n eso-demo

Check the resulting Kubernetes Secret.

Check synchronized Secret

kubectl get secret kakaocloud-synced-secret -n eso-demo

To check only the data keys without exposing Secret values:

Check data keys only

kubectl get secret kakaocloud-synced-secret \
  -n eso-demo \
  -o go-template='{{range $key, $value := .data}}{{$key}}{{"\n"}}{{end}}'

Basic synchronization is complete when the ExternalSecret has READY=True and STATUS=SecretSynced, and the target Secret contains the password key.

Troubleshooting

If installation or synchronization fails, see ESO integration troubleshooting for symptom-specific checks.

Next steps

After completing basic synchronization, continue with Synchronize and refresh a secret. This tutorial reuses the current namespace, credentials, and SecretStore and uses a separate synchronization resource to verify value updates after changing the default version. To continue, do not delete the practice resources below; go directly to the next tutorial.

Clean up practice resources

Delete practice resources

If you also completed the next tutorial or the service guide examples, first complete Clean up resources in the secret usage tutorial. The commands below delete the basic synchronization resources, SecretStore, and IAM credentials Secret created in this tutorial.

Delete practice resources

kubectl delete externalsecret kakaocloud-external-secret -n eso-demo
kubectl delete secretstore kakaocloud-secret-store -n eso-demo
kubectl delete secret kakaocloud-credentials -n eso-demo

If you no longer use the practice namespace, delete it.

Delete the namespace

kubectl delete namespace eso-demo

Uninstall ESO

Caution

With this tutorial's chart and installation settings, the command below also deletes ESO CRDs and their custom resources. Kubernetes Secrets created with creationPolicy: Owner are also deleted, which can affect workloads that reference them. Do not run it if ESO is used in another namespace.

Uninstall ESO

helm uninstall external-secrets -n external-secrets