Manage OKE with Argo CD
Operate OKE through Git. Treat Git as desired state and Kubernetes/Argo CD as
observation surfaces. Do not repair managed objects directly.
Start every task
- Locate the repository and run
scripts/preflight.sh [path].
- Identify the target cluster, namespace, application, component, and
environment. Do not guess a missing target that changes placement.
- Classify the request with references/use-cases.md.
- Read references/repository-contracts.md.
- Read only the task-specific reference:
- local platform or developer application:
references/applications.md;
- managed spoke: references/fleet.md;
- failure or rollback:
references/operations.md.
- Apply references/safety.md before editing or running
a command that changes external state.
Repository ownership
For stack scope, bootstrap credentials, IAM placement, or upgrades, read
references/bootstrap.md. In cluster_admin,
apps-config is absent by design; do not create its source or developer
placements unless the user explicitly enables application management.
cluster-config: bootstrap, Argo configuration, cluster resources (including
every resource rendered into kube-system), namespace infrastructure, and
local placement. Owned by cluster administrators.
apps-config: reusable developer components and dev, staging, and
production variants. It never selects a cluster.
fleet-config: optional registered-spoke objects, profiles, and per-cluster
placement. Spokes run no local GitOps controller.
gitops-pipelines: OCI DevOps artifact mirroring. Do not place Kubernetes desired
state here.
In a hybrid installation, OCI DevOps may own component builds and releases while
this repository owns cluster administration. Sharing an OCI DevOps project does
not transfer Kubernetes ownership: do not add developer component workloads here
unless the selected GitOps scope explicitly includes application placement.
If a requested change crosses repositories, make and validate one coherent
change per repository and state the required merge order.
Change workflow
- Update the clone from
main without discarding user changes.
- Inspect existing descriptors and every referenced path.
- Prefer the supported descriptor or application-parent contract over editing
generated ApplicationSets.
- Make the smallest coherent change. Preserve component/environment as the
release and rollback boundary.
- Run
scripts/validate.sh [repository-root].
- Run
scripts/impact.sh [repository-root] [base-ref] and review every delete,
descriptor removal, list-element removal, namespace change, and target
change.
- Compare before/after rendered output for each changed deployment unit:
- Kustomize:
scripts/diff-kustomize.sh <repo> <overlay-path> [base-ref];
- umbrella Helm:
scripts/diff-helm-selection.sh <repo> <app> <component> <environment> [base-ref].
Do not call every object in a render “changed.”
- Show the user the planned resources and pruning impact before destructive or
externally mutating operations.
- Commit through the repository's normal review workflow. Do not push, merge,
run a pipeline, apply bootstrap, or change a live cluster unless the user
authorized that action.
- After merge, observe the generated Application and workload. Fix or revert
Git when desired state is wrong.
Validation rules
- Render every changed Kustomize root with
kubectl kustomize.
- For umbrella Helm, lint and template every affected component/environment
using global values first and the selected values file last.
- Inspect rendered names, namespaces, labels, images, resource requests, and
duplicate identities.
- Verify a Helm environment file enables exactly one subchart.
- Never render or print secret values into logs.
- Use server-side dry-run only when cluster access exists and the user permits
live read/API interaction. Local rendering remains mandatory.
Observe Argo CD
Run on the hub:
kubectl -n argocd get applicationsets,applications
kubectl -n argocd describe application <application>
For a spoke, confirm the generated Application destination is the registered
private API endpoint. Then inspect the workload namespace. Expect Synced and
Healthy; read conditions and events before acting on other states.
Report every result
Include:
- target cluster, namespace, application, component, and environment;
- repository and every created, modified, or deleted file;
- validation commands and outcomes;
- Applications and Kubernetes resources proven by before/after rendering to
change or be pruned; list unchanged rendered resources separately only when
useful;
- external actions performed or still requiring authorization;
- exact Git revert or rollback procedure.
Use templates in assets/ only as starting points. Replace every __TOKEN__,
inspect the result, and adapt it to existing repository conventions before
committing. Read references/templates.md before
copying an asset.
1---2name: manage-oke-with-argocd3description: Manage Oracle Kubernetes Engine clusters through this solution's Argo CD GitOps repositories. Use for bootstrapping or observing Argo CD, changing cluster-scoped or namespaced resources, deploying Helm charts, managing environment-aware Kustomize or umbrella-Helm applications, releasing one component, handling OCI Vault ExternalSecrets, registering or configuring private-endpoint spoke clusters, validating changes, analyzing pruning impact, troubleshooting reconciliation, and rolling back through Git in cluster-config, apps-config, or fleet-config repositories.4metadata:5 source: https://skillmd.com/skills/oracle-devrel/manage-oke-with-argocd6---78# Manage OKE with Argo CD910Operate OKE through Git. Treat Git as desired state and Kubernetes/Argo CD as11observation surfaces. Do not repair managed objects directly.1213## Start every task14151. Locate the repository and run `scripts/preflight.sh [path]`.162. Identify the target cluster, namespace, application, component, and17 environment. Do not guess a missing target that changes placement.183. Classify the request with [references/use-cases.md](references/use-cases.md).194. Read [references/repository-contracts.md](references/repository-contracts.md).205. Read only the task-specific reference:21 - local platform or developer application:22 [references/applications.md](references/applications.md);23 - managed spoke: [references/fleet.md](references/fleet.md);24 - failure or rollback:25 [references/operations.md](references/operations.md).266. Apply [references/safety.md](references/safety.md) before editing or running27 a command that changes external state.2829## Repository ownership3031For stack scope, bootstrap credentials, IAM placement, or upgrades, read32[references/bootstrap.md](references/bootstrap.md). In `cluster_admin`,33`apps-config` is absent by design; do not create its source or developer34placements unless the user explicitly enables application management.3536- `cluster-config`: bootstrap, Argo configuration, cluster resources (including37 every resource rendered into `kube-system`), namespace infrastructure, and38 local placement. Owned by cluster administrators.39- `apps-config`: reusable developer components and `dev`, `staging`, and40 `production` variants. It never selects a cluster.41- `fleet-config`: optional registered-spoke objects, profiles, and per-cluster42 placement. Spokes run no local GitOps controller.43- `gitops-pipelines`: OCI DevOps artifact mirroring. Do not place Kubernetes desired44 state here.4546In a hybrid installation, OCI DevOps may own component builds and releases while47this repository owns cluster administration. Sharing an OCI DevOps project does48not transfer Kubernetes ownership: do not add developer component workloads here49unless the selected GitOps scope explicitly includes application placement.5051If a requested change crosses repositories, make and validate one coherent52change per repository and state the required merge order.5354## Change workflow55561. Update the clone from `main` without discarding user changes.572. Inspect existing descriptors and every referenced path.583. Prefer the supported descriptor or application-parent contract over editing59 generated ApplicationSets.604. Make the smallest coherent change. Preserve component/environment as the61 release and rollback boundary.625. Run `scripts/validate.sh [repository-root]`.636. Run `scripts/impact.sh [repository-root] [base-ref]` and review every delete,64 descriptor removal, list-element removal, namespace change, and target65 change.667. Compare before/after rendered output for each changed deployment unit:67 - Kustomize: `scripts/diff-kustomize.sh <repo> <overlay-path> [base-ref]`;68 - umbrella Helm: `scripts/diff-helm-selection.sh <repo> <app> <component> <environment> [base-ref]`.69 Do not call every object in a render “changed.”708. Show the user the planned resources and pruning impact before destructive or71 externally mutating operations.729. Commit through the repository's normal review workflow. Do not push, merge,73 run a pipeline, apply bootstrap, or change a live cluster unless the user74 authorized that action.7510. After merge, observe the generated Application and workload. Fix or revert76 Git when desired state is wrong.7778## Validation rules7980- Render every changed Kustomize root with `kubectl kustomize`.81- For umbrella Helm, lint and template every affected component/environment82 using global values first and the selected values file last.83- Inspect rendered names, namespaces, labels, images, resource requests, and84 duplicate identities.85- Verify a Helm environment file enables exactly one subchart.86- Never render or print secret values into logs.87- Use server-side dry-run only when cluster access exists and the user permits88 live read/API interaction. Local rendering remains mandatory.8990## Observe Argo CD9192Run on the hub:9394```bash95kubectl -n argocd get applicationsets,applications96kubectl -n argocd describe application <application>97```9899For a spoke, confirm the generated Application destination is the registered100private API endpoint. Then inspect the workload namespace. Expect `Synced` and101`Healthy`; read conditions and events before acting on other states.102103## Report every result104105Include:106107- target cluster, namespace, application, component, and environment;108- repository and every created, modified, or deleted file;109- validation commands and outcomes;110- Applications and Kubernetes resources proven by before/after rendering to111 change or be pruned; list unchanged rendered resources separately only when112 useful;113- external actions performed or still requiring authorization;114- exact Git revert or rollback procedure.115116Use templates in `assets/` only as starting points. Replace every `__TOKEN__`,117inspect the result, and adapt it to existing repository conventions before118committing. Read [references/templates.md](references/templates.md) before119copying an asset.