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.
Declarative configuration
Section titled “Declarative configuration”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
Section titled “ConfigMaps”ConfigMaps are found by fixed, well-known names:
| ConfigMap | Holds |
|---|---|
argocd-cm | General server settings, including local user accounts and single sign-on (OIDC, Dex) configuration |
argocd-cmd-params-cm | Launch parameters for the components, such as server.insecure |
argocd-rbac-cm | RBAC policies and group-to-role mappings |
argocd-ssh-known-hosts-cm | Public SSH host keys for authenticating to Git repositories |
argocd-tls-certs-cm | Custom TLS certificates for HTTPS repositories |
argocd-gpg-keys-cm | Public GPG keys for verifying commit signatures |
argocd-notifications-cm | Notification 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: v1kind: ConfigMapmetadata: name: argocd-cmd-params-cm namespace: argocd labels: app.kubernetes.io/part-of: argocd # required, otherwise the ConfigMap is not useddata: server.insecure: "true" # API server: serve plain HTTP, TLS ends at the ingress controller.log.format: "json" # application controller: JSON logsSecrets
Section titled “Secrets”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 value | Contents |
|---|---|
cluster | API endpoint, configuration, and credentials of a target cluster |
repository | Connection settings and credentials (SSH key, token) for one repository |
repo-creds | Shared credentials reused by every repository whose URL matches a prefix |
repo-config | Extra configuration for a repository, rarely used |
repository-write | Credentials Argo CD uses to write to a repository |
repo-write-creds | Shared write credentials, reused across repositories |
scm-creds | Credentials for source control management providers |
A repository registered declaratively:
apiVersion: v1kind: Secretmetadata: name: private-repo namespace: argocd labels: argocd.argoproj.io/secret-type: repository # how Argo CD finds this SecretstringData: 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.
Specification and reference
Section titled “Specification and reference”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:
| Service | Covers |
|---|---|
AccountService, SessionService | Local accounts and session tokens |
ApplicationService, ApplicationSetService | Creating, syncing, and monitoring Applications and ApplicationSets |
ClusterService, ProjectService | Target clusters and AppProjects |
RepositoryService, RepoCredsService | Repositories and their credentials |
CertificateService, GPGKeyService | Repository TLS certificates and commit verification keys |
SettingsService, VersionService | Server settings and version |
Authenticating
Section titled “Authenticating”Protected endpoints need a session token. Post credentials to /api/v1/session, then send the token as a bearer token on later calls:
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" | jqThe 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.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Likely cause | Fix |
|---|---|---|
| A ConfigMap change has no effect | The ConfigMap lacks the app.kubernetes.io/part-of: argocd label, or the component has not picked up a changed parameter | Add the label. Restart the affected component if the setting is a launch parameter |
| A repository or cluster Secret is ignored | Missing or misspelled argocd.argoproj.io/secret-type label, or the Secret is outside the Argo CD namespace | Fix the label and apply the Secret in the argocd namespace |
API call returns 401 | Token missing, expired, or sent without the Bearer prefix | Request a new token and send Authorization: Bearer <token> |
/swagger-ui has no way to send a request | The page is a read-only reference | Call the endpoint with curl or the CLI |