Skip to content
Documentation Background

Declarative configuration and API

The UI and CLI are two clients of one API, and the server’s configuration is ordinary Kubernetes objects. That gives two routes beyond the clients: declare configuration as ConfigMaps and Secrets that live in Git, or call the API directly and bypass any limit the UI or CLI imposes.


Argo CD applies its own controller pattern to itself. Each component reads its settings from objects in the Argo CD namespace, so an administrator can manage the whole server by applying manifests instead of clicking through the UI or running CLI commands. Because the objects are plain YAML, they can be stored in Git and managed by Argo CD.

ConfigMaps are found by fixed, well-known names:

ConfigMapHolds
argocd-cmGeneral server settings, including local user accounts and single sign-on (OIDC, Dex) configuration
argocd-cmd-params-cmLaunch parameters for the components, such as server.insecure
argocd-rbac-cmRBAC policies and group-to-role mappings
argocd-ssh-known-hosts-cmPublic SSH host keys for authenticating to Git repositories
argocd-tls-certs-cmCustom TLS certificates for HTTPS repositories
argocd-gpg-keys-cmPublic GPG keys for verifying commit signatures
argocd-notifications-cmNotification triggers, templates, and services

A ConfigMap managed outside the install manifests must carry the label app.kubernetes.io/part-of: argocd, or Argo CD ignores it. Component parameters take a prefix per component: server. for the API server, reposerver. for the repo server, controller. for the application controller, and no prefix for flags shared between them.

apiVersion: v1
kind: ConfigMap
metadata:
name: argocd-cmd-params-cm
namespace: argocd
labels:
app.kubernetes.io/part-of: argocd # required, otherwise the ConfigMap is not used
data:
server.insecure: "true" # API server: serve plain HTTP, TLS ends at the ingress
controller.log.format: "json" # application controller: JSON logs

Secrets follow a different rule. A handful have fixed names (argocd-secret, argocd-notifications-secret, and the generated argocd-initial-admin-secret). Everything else is discovered by the label argocd.argoproj.io/secret-type, so a cluster can hold as many repository and cluster Secrets as needed, each with its own name.

Label valueContents
clusterAPI endpoint, configuration, and credentials of a target cluster
repositoryConnection settings and credentials (SSH key, token) for one repository
repo-credsShared credentials reused by every repository whose URL matches a prefix
repo-configExtra configuration for a repository, rarely used
repository-writeCredentials Argo CD uses to write to a repository
repo-write-credsShared write credentials, reused across repositories
scm-credsCredentials for source control management providers

A repository registered declaratively:

apiVersion: v1
kind: Secret
metadata:
name: private-repo
namespace: argocd
labels:
argocd.argoproj.io/secret-type: repository # how Argo CD finds this Secret
stringData:
type: git
url: https://git.example.com/org/app.git
username: <username>
password: <token>

Every operation in the UI and CLI is a call to the API server, which accepts gRPC and REST. Calling it directly lets scripts and external systems do anything the server supports, including tasks the clients hide.

Argo CD publishes its OpenAPI specification as JSON at /swagger.json. The spec describes every endpoint with its inputs and outputs, and for a mature API it is long. Opening /swagger-ui on the server renders it as a browsable reference. In 3.5 the page is rendered with ReDoc, so it documents the endpoints but does not send requests. Use curl or the CLI to call them.

Endpoints are grouped into services:

ServiceCovers
AccountService, SessionServiceLocal accounts and session tokens
ApplicationService, ApplicationSetServiceCreating, syncing, and monitoring Applications and ApplicationSets
ClusterService, ProjectServiceTarget clusters and AppProjects
RepositoryService, RepoCredsServiceRepositories and their credentials
CertificateService, GPGKeyServiceRepository TLS certificates and commit verification keys
SettingsService, VersionServiceServer settings and version

Protected endpoints need a session token. Post credentials to /api/v1/session, then send the token as a bearer token on later calls:

Terminal window
ARGOCD_SERVER=argocd.example.com
TOKEN=$(curl -s -H "Content-Type: application/json" \
-X POST "https://$ARGOCD_SERVER/api/v1/session" \
-d '{"username":"admin","password":"<PASSWORD>"}' | jq -r .token)
curl -s -H "Authorization: Bearer $TOKEN" \
"https://$ARGOCD_SERVER/api/v1/settings" | jq

The first call returns {"token":"<TOKEN>"}. The SettingsService endpoint at /api/v1/settings shows server configuration in more depth than the UI or CLI, including appLabelKey and passwordPattern. It reflects what is stored in argocd-cm, so a change made declaratively appears here.


SymptomLikely causeFix
A ConfigMap change has no effectThe ConfigMap lacks the app.kubernetes.io/part-of: argocd label, or the component has not picked up a changed parameterAdd the label. Restart the affected component if the setting is a launch parameter
A repository or cluster Secret is ignoredMissing or misspelled argocd.argoproj.io/secret-type label, or the Secret is outside the Argo CD namespaceFix the label and apply the Secret in the argocd namespace
API call returns 401Token missing, expired, or sent without the Bearer prefixRequest a new token and send Authorization: Bearer <token>
/swagger-ui has no way to send a requestThe page is a read-only referenceCall the endpoint with curl or the CLI