From c9d3c1a9f41711e4e3cef49984d3f3c483049785 Mon Sep 17 00:00:00 2001 From: Liam Mackie Date: Thu, 23 Jul 2026 18:12:22 +1000 Subject: [PATCH 1/2] Add docs for Argo Gateway cross-space --- src/pages/docs/argo-cd/annotations/index.md | 29 +++++++++++- .../instances/automated-installation.md | 47 ++++++++++++++++++- 2 files changed, 74 insertions(+), 2 deletions(-) diff --git a/src/pages/docs/argo-cd/annotations/index.md b/src/pages/docs/argo-cd/annotations/index.md index b9872a3d41..c87a49204d 100644 --- a/src/pages/docs/argo-cd/annotations/index.md +++ b/src/pages/docs/argo-cd/annotations/index.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2025-09-15 -modDate: 2025-09-15 +modDate: 2026-07-21 title: Scoping Annotations description: What annotations are required to link Argo CD applications to Octopus Projects/Environments/Tenants navTitle: Scoping Annotations @@ -93,6 +93,33 @@ spec: name: guestbook-service-2 ``` +## Scoping applications to spaces + +When a gateway is [registered in multiple spaces](/docs/argo-cd/instances/automated-installation#registering-a-gateway-in-multiple-spaces), applications from that Argo CD instance appear in every space the gateway is registered in. If an application should only appear in some of those spaces, add the `argo.octopus.com/space` annotation. + +| Annotation | Required | Value description | +| ------------------------ | -------- | ------------------------------------------------------------- | +| `argo.octopus.com/space` | false | A comma-separated list of Octopus Space *slugs* | + +The space annotation applies to the whole application and cannot be source-scoped. If the annotation is not present, the application appears in all spaces the gateway is registered in, so you only need it when application names would collide across spaces. + +```yaml +apiVersion: argoproj.io/v1alpha1 +kind: Application +metadata: + name: guestbook + namespace: argocd + annotations: + argo.octopus.com/space: space-one, space-two + argo.octopus.com/environment: development + argo.octopus.com/project: argo-cd-guestbook +spec: + source: + repoURL: https://github.com/example-org/guestbook.git + targetRevision: HEAD + path: ./ +``` + ## Updating in Argo CD Web UI You can update the annotations for an Argo CD Application via the Argo CD Web UI. diff --git a/src/pages/docs/argo-cd/instances/automated-installation.md b/src/pages/docs/argo-cd/instances/automated-installation.md index 0b771cd880..6b1fa3c53a 100644 --- a/src/pages/docs/argo-cd/instances/automated-installation.md +++ b/src/pages/docs/argo-cd/instances/automated-installation.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2025-09-15 -modDate: 2026-03-26 +modDate: 2026-07-21 title: Automated Installation description: Install Argo CD instances via scripting or IAC navOrder: 10 @@ -111,6 +111,51 @@ resource "helm_release" "argo_gateway" { } ``` +## Registering a gateway in multiple spaces + +From 2026.x.y onwards, a single gateway installation can be registered in more than one space, making the same Argo CD instance available in each of them. + +By default, every registered space discovers all of the instance's applications. To limit an application to specific spaces, use the [space scoping annotation](/docs/argo-cd/annotations#scoping-applications-to-spaces). + +### Using Helm values + +Set `registration.octopus.spaceIds` and the gateway registers itself into each listed space: + +```bash +--set 'registration.octopus.spaceIds={Spaces-1,Spaces-2,Spaces-3}' \ +``` + +### Using the REST API + +You can also register an already-installed gateway in another space with the REST API by setting `PreserveAuthenticationToken` to `true`. + +First, find the gateway's client ID by getting its registration from the space it was initially installed into. The gateway ID (e.g. `ArgoCDGateways-1`) is shown in the URL of the Argo CD instance page in Octopus. + +```bash +curl -H "X-Octopus-ApiKey: API-YOUR-KEY" \ + "https://your-octopus-url/api/Spaces-1/argocdgateways/ArgoCDGateways-1" +``` + +The response includes a `ClientId` value, which is used to re-register the gateway in the new space. To run the registration in a new space: + +```bash +curl -X POST \ + -H "X-Octopus-ApiKey: API-YOUR-KEY" \ + -H "Content-Type: application/json" \ + "https://your-octopus-url/api//argocdgateways" \ + -d '{ + "SpaceId": "", + "ClientId": "", + "Name": "", + "Environments": [], + "PreserveAuthenticationToken": true + }' +``` + +When `PreserveAuthenticationToken` is `true`, the response's `AuthenticationToken` is null and the existing token remains valid. + +Deleting a registration only removes the gateway from that space. The gateway's authentication token stays valid while it's registered in at least one space. + ## Installing as an Argo CD Application The Octopus-Argo Gateway's helm chart can be installed via an Argo CD Application. From ff58846389cbc1948474ba5e8049abd64b3d4ead Mon Sep 17 00:00:00 2001 From: Liam Mackie Date: Fri, 24 Jul 2026 12:34:05 +1000 Subject: [PATCH 2/2] version --- .../instances/automated-installation.md | 100 +++++++++--------- 1 file changed, 50 insertions(+), 50 deletions(-) diff --git a/src/pages/docs/argo-cd/instances/automated-installation.md b/src/pages/docs/argo-cd/instances/automated-installation.md index 6b1fa3c53a..faba3aed43 100644 --- a/src/pages/docs/argo-cd/instances/automated-installation.md +++ b/src/pages/docs/argo-cd/instances/automated-installation.md @@ -113,7 +113,7 @@ resource "helm_release" "argo_gateway" { ## Registering a gateway in multiple spaces -From 2026.x.y onwards, a single gateway installation can be registered in more than one space, making the same Argo CD instance available in each of them. +From `2026.3.7755` onwards, a single gateway installation can be registered in more than one space, making the same Argo CD instance available in each of them. By default, every registered space discovers all of the instance's applications. To limit an application to specific spaces, use the [space scoping annotation](/docs/argo-cd/annotations#scoping-applications-to-spaces). @@ -164,61 +164,61 @@ The application YAML required to install the helm chart is as follows (replacing 1. Create the namespace - ```shell - kubectl create ns octopus-argo-gateway-your-namespace - ``` + ```shell + kubectl create ns octopus-argo-gateway-your-namespace + ``` 2. Generate Argo CD Authentication Token - 2.1. Follow the instructions on the [Argo CD Authentication](/docs/argo-cd/instances/argo-user) guide - 2.2. Save the token in a secret + 2.1. Follow the instructions on the [Argo CD Authentication](/docs/argo-cd/instances/argo-user) guide + 2.2. Save the token in a secret - ```shell - kubectl create secret generic argocd-auth-token -n octopus-argo-gateway-your-namespace --from-literal=ARGOCD_AUTH_TOKEN= - ``` + ```shell + kubectl create secret generic argocd-auth-token -n octopus-argo-gateway-your-namespace --from-literal=ARGOCD_AUTH_TOKEN= + ``` 3. Generate Octopus Deploy Api-Key - 3.1. Follow the instructions on the [How to Create an API Key](/docs/octopus-rest-api/how-to-create-an-api-key) guide - 3.2. Save the token in a secret + 3.1. Follow the instructions on the [How to Create an API Key](/docs/octopus-rest-api/how-to-create-an-api-key) guide + 3.2. Save the token in a secret - ```shell - kubectl create secret generic octopus-server-access-token -n octopus-argo-gateway-your-namespace --from-literal=OCTOPUS_SERVER_ACCESS_TOKEN= - ``` + ```shell + kubectl create secret generic octopus-server-access-token -n octopus-argo-gateway-your-namespace --from-literal=OCTOPUS_SERVER_ACCESS_TOKEN= + ``` 4. Apply the Argo CD application (or commit this manifest to your git-ops repository already synced by Argo CD) - ```yaml - apiVersion: argoproj.io/v1alpha1 - kind: Application - metadata: - finalizers: - - resources-finalizer.argocd.argoproj.io - name: octopus-argo-gateway - spec: - project: default - source: - repoURL: registry-1.docker.io/octopusdeploy - chart: octopus-argocd-gateway-chart - targetRevision: 1.23.0 - helm: - valuesObject: - registration: - octopus: - name: - serverApiUrl: https://your-instance.octopus.app - serverAccessTokenSecretName: octopus-server-access-token - serverAccessTokenSecretKey: OCTOPUS_SERVER_ACCESS_TOKEN - spaceId: Spaces-1 - gateway: - octopus: - serverGrpcUrl: grpc://your-instance.octopus.app:8443 - argocd: - serverGrpcUrl: grpc://argocd-server.argocd.svc.cluster.local - authenticationTokenSecretName: argocd-auth-token - authenticationTokenSecretKey: ARGOCD_AUTH_TOKEN - autoUpdate: - # should be disabled, otherwise the auto-update job will keep trying to update the instance, while argo cd syncs it back to original state - enabled: false - destination: - server: https://kubernetes.default.svc - namespace: octopus-argo-gateway-your-namespace - ``` + ```yaml + apiVersion: argoproj.io/v1alpha1 + kind: Application + metadata: + finalizers: + - resources-finalizer.argocd.argoproj.io + name: octopus-argo-gateway + spec: + project: default + source: + repoURL: registry-1.docker.io/octopusdeploy + chart: octopus-argocd-gateway-chart + targetRevision: 1.23.0 + helm: + valuesObject: + registration: + octopus: + name: + serverApiUrl: https://your-instance.octopus.app + serverAccessTokenSecretName: octopus-server-access-token + serverAccessTokenSecretKey: OCTOPUS_SERVER_ACCESS_TOKEN + spaceId: Spaces-1 + gateway: + octopus: + serverGrpcUrl: grpc://your-instance.octopus.app:8443 + argocd: + serverGrpcUrl: grpc://argocd-server.argocd.svc.cluster.local + authenticationTokenSecretName: argocd-auth-token + authenticationTokenSecretKey: ARGOCD_AUTH_TOKEN + autoUpdate: + # should be disabled, otherwise the auto-update job will keep trying to update the instance, while argo cd syncs it back to original state + enabled: false + destination: + server: https://kubernetes.default.svc + namespace: octopus-argo-gateway-your-namespace + ```