Add docs for Argo Gateway cross-space

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.

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.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).
+
+### 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/<new space ID>/argocdgateways" \
+  -d '{
+    "SpaceId": "<new space ID>",
+    "ClientId": "<client id from the existing registration>",
+    "Name": "<display name of gateway in Octopus>",
+    "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.
@@ -119,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=<token>
-    ```
+   ```shell
+   kubectl create secret generic argocd-auth-token -n octopus-argo-gateway-your-namespace --from-literal=ARGOCD_AUTH_TOKEN=<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=<token>
-    ```
+   ```shell
+   kubectl create secret generic octopus-server-access-token -n octopus-argo-gateway-your-namespace --from-literal=OCTOPUS_SERVER_ACCESS_TOKEN=<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: <display name of gateway in Octopus>
-                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: <display name of gateway in Octopus>
+               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
+   ```