Skip to content

Update connect agent docs #1167

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cbuto merged 2 commits into from
May 7, 2026
Merged

Update connect agent docs #1167

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f889e5a
Update agent docs with proxy info + new values
cbuto Apr 9, 2026
851e03d
Note proxy/zcaler
cbuto May 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 54 additions & 5 deletions self-hosted-spaces-docs/howtos/attach-detach.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,14 +81,63 @@ In the same cluster where you installed the Spaces software, install the Upbound
```bash
helm -n upbound-system upgrade --install agent \
Copy link
Copy Markdown
Contributor Author

@cbuto cbuto May 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@tr0njavolta with the new versioning scheme, what do these files do? 😅

Copy link
Copy Markdown
Member

@tr0njavolta tr0njavolta May 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll update the docs README for this but the mirroring in this PR is good now.

oci://xpkg.upbound.io/spaces-artifacts/agent \
--version "0.0.0-441.g68777b9" \
--version "0.0.0-1116.g14cbfe6" \
Copy link
Copy Markdown
Contributor

@branden branden May 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pinning the version in docs is a bummer, but I guess it frees us up to make breaking changes without unintended disruption.

Copy link
Copy Markdown
Contributor Author

@cbuto cbuto May 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeah agreed overall

--set "global.space=${UPBOUND_SPACE_NAME}" \
--set "global.organization=${UPBOUND_ORG_NAME}" \
--set "global.tokenSecret=connect-token" \
--set "image.repository=xpkg.upbound.io/spaces-artifacts/agent" \
--set "registration.image.repository=xpkg.upbound.io/spaces-artifacts/register-init" \
--set "registration.enabled=true" \
--set "imagePullSecrets[0].name=upbound-pull-secret" \
--set "billing.enabled=false" \
--wait
```

#### Use an HTTP proxy

The Connect agent respects `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` for outbound traffic to Upbound. Set them on the agent with `extraEnv` and on the registration init container with `registration.extraEnv`. If you use Zscaler or a similar corporate forward proxy, use the same pattern for both as shown below.

| Variable | Description |
| --- | --- |
| `HTTP_PROXY` | HTTP proxy URL |
| `HTTPS_PROXY` | HTTPS proxy URL |
| `NO_PROXY` | Comma-separated hosts that bypass the proxy |

Example `agent-proxy-values.yaml`:

```yaml
extraEnv:
- name: HTTP_PROXY
value: "http://proxy.example.com:8080"
- name: HTTPS_PROXY
value: "http://proxy.example.com:8080"
- name: NO_PROXY
value: "10.0.0.0/8,.svc.cluster.local,localhost,127.0.0.1"
registration:
extraEnv:
- name: HTTP_PROXY
value: "http://proxy.example.com:8080"
- name: HTTPS_PROXY
value: "http://proxy.example.com:8080"
- name: NO_PROXY
value: "10.0.0.0/8,.svc.cluster.local,localhost,127.0.0.1"
```

Install or upgrade using that file:

```bash
helm -n upbound-system upgrade --install agent \
oci://xpkg.upbound.io/spaces-artifacts/agent \
--version "0.0.0-1116.g14cbfe6" \
--set "global.space=${UPBOUND_SPACE_NAME}" \
--set "global.organization=${UPBOUND_ORG_NAME}" \
--set "global.tokenSecret=connect-token" \
--set "image.repository=xpkg.upbound.io/spaces-artifacts/agent" \
--set "registration.image.repository=xpkg.upbound.io/spaces-artifacts/register-init" \
--set "registration.enabled=true" \
--set "space=${UPBOUND_SPACE_NAME}" \
--set "organization=${UPBOUND_ORG_NAME}" \
--set "tokenSecret=connect-token" \
--set "imagePullSecrets[0].name=upbound-pull-secret" \
--set "billing.enabled=false" \
-f agent-proxy-values.yaml \
--wait
```

Expand Down Expand Up @@ -173,7 +222,7 @@ Users interact with the Upbound Console to generate request queries to the Upbou

:::important
This data only concerns resource configuration. The data _inside_ the managed
resource in your Space isn't visible at any point.
resource in your Space isn't visible at any point.
:::

**Upbound can't see your data.** Upbound doesn't have access to session-based data rendered for your users in the Upbound Console. Upbound has no information about your self-hosted Space, other than that you've connected a self-hosted Space.
Expand Down
17 changes: 10 additions & 7 deletions self-hosted-spaces-docs/self-hosted-spaces-quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -185,7 +185,7 @@ up robot create "${UPBOUND_SPACE_NAME}" --description="Robot used for connect ag
export UPBOUND_TOKEN=$(up robot token create "${UPBOUND_SPACE_NAME}" "${UPBOUND_SPACE_NAME}-token" -ojson | jq -r .token)
```

Create a Kubernetes secret from the token:
Create a secret containing the robot token:

```bash
kubectl create secret -n upbound-system generic connect-token \
Expand All @@ -195,20 +195,23 @@ kubectl create secret -n upbound-system generic connect-token \
Log into the Helm OCI registry using your license token:

```bash
jq -r .token $SPACES_TOKEN_PATH | helm registry login xpkg.upbound.io \
--username upbound --password-stdin
jq -r .token $SPACES_TOKEN_PATH | helm registry login xpkg.upbound.io -u $(jq -r .accessId $SPACES_TOKEN_PATH) --password-stdin
```

Install the connect agent:

```bash
helm -n upbound-system upgrade --install agent \
oci://xpkg.upbound.io/spaces-artifacts/agent \
--set "imagePullSecrets[0].name=upbound-pull-secret" \
--version "0.0.0-1116.g14cbfe6" \
--set "global.space=${UPBOUND_SPACE_NAME}" \
--set "global.organization=${UPBOUND_ORG_NAME}" \
--set "global.tokenSecret=connect-token" \
--set "image.repository=xpkg.upbound.io/spaces-artifacts/agent" \
--set "registration.image.repository=xpkg.upbound.io/spaces-artifacts/register-init" \
--set "registration.enabled=true" \
--set "space=${UPBOUND_SPACE_NAME}" \
--set "organization=${UPBOUND_ORG_NAME}" \
--set "tokenSecret=connect-token" \
--set "imagePullSecrets[0].name=upbound-pull-secret" \
--set "billing.enabled=false" \
--wait
```

Expand Down
59 changes: 54 additions & 5 deletions self-hosted-spaces_versioned_docs/version-1.14/howtos/attach-detach.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,14 +81,63 @@ In the same cluster where you installed the Spaces software, install the Upbound
```bash
helm -n upbound-system upgrade --install agent \
oci://xpkg.upbound.io/spaces-artifacts/agent \
--version "0.0.0-441.g68777b9" \
--version "0.0.0-1116.g14cbfe6" \
--set "global.space=${UPBOUND_SPACE_NAME}" \
--set "global.organization=${UPBOUND_ORG_NAME}" \
--set "global.tokenSecret=connect-token" \
--set "image.repository=xpkg.upbound.io/spaces-artifacts/agent" \
--set "registration.image.repository=xpkg.upbound.io/spaces-artifacts/register-init" \
--set "registration.enabled=true" \
--set "imagePullSecrets[0].name=upbound-pull-secret" \
--set "billing.enabled=false" \
--wait
```

#### Use an HTTP proxy

The Connect agent respects `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` for outbound traffic to Upbound. Set them on the agent with `extraEnv` and on the registration init container with `registration.extraEnv`. If you use Zscaler or a similar corporate forward proxy, use the same pattern for both as shown below.

| Variable | Description |
| --- | --- |
| `HTTP_PROXY` | HTTP proxy URL |
| `HTTPS_PROXY` | HTTPS proxy URL |
| `NO_PROXY` | Comma-separated hosts that bypass the proxy |

Example `agent-proxy-values.yaml`:

```yaml
extraEnv:
- name: HTTP_PROXY
value: "http://proxy.example.com:8080"
- name: HTTPS_PROXY
value: "http://proxy.example.com:8080"
- name: NO_PROXY
value: "10.0.0.0/8,.svc.cluster.local,localhost,127.0.0.1"
registration:
extraEnv:
- name: HTTP_PROXY
value: "http://proxy.example.com:8080"
- name: HTTPS_PROXY
value: "http://proxy.example.com:8080"
- name: NO_PROXY
value: "10.0.0.0/8,.svc.cluster.local,localhost,127.0.0.1"
```

Install or upgrade using that file:

```bash
helm -n upbound-system upgrade --install agent \
oci://xpkg.upbound.io/spaces-artifacts/agent \
--version "0.0.0-1116.g14cbfe6" \
--set "global.space=${UPBOUND_SPACE_NAME}" \
--set "global.organization=${UPBOUND_ORG_NAME}" \
--set "global.tokenSecret=connect-token" \
--set "image.repository=xpkg.upbound.io/spaces-artifacts/agent" \
--set "registration.image.repository=xpkg.upbound.io/spaces-artifacts/register-init" \
--set "registration.enabled=true" \
--set "space=${UPBOUND_SPACE_NAME}" \
--set "organization=${UPBOUND_ORG_NAME}" \
--set "tokenSecret=connect-token" \
--set "imagePullSecrets[0].name=upbound-pull-secret" \
--set "billing.enabled=false" \
-f agent-proxy-values.yaml \
--wait
```

Expand Down Expand Up @@ -173,7 +222,7 @@ Users interact with the Upbound Console to generate request queries to the Upbou

:::important
This data only concerns resource configuration. The data _inside_ the managed
resource in your Space isn't visible at any point.
resource in your Space isn't visible at any point.
:::

**Upbound can't see your data.** Upbound doesn't have access to session-based data rendered for your users in the Upbound Console. Upbound has no information about your self-hosted Space, other than that you've connected a self-hosted Space.
Expand Down
17 changes: 10 additions & 7 deletions self-hosted-spaces_versioned_docs/version-1.14/self-hosted-spaces-quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -185,7 +185,7 @@ up robot create "${UPBOUND_SPACE_NAME}" --description="Robot used for connect ag
export UPBOUND_TOKEN=$(up robot token create "${UPBOUND_SPACE_NAME}" "${UPBOUND_SPACE_NAME}-token" -ojson | jq -r .token)
```

Create a Kubernetes secret from the token:
Create a secret containing the robot token:

```bash
kubectl create secret -n upbound-system generic connect-token \
Expand All @@ -195,20 +195,23 @@ kubectl create secret -n upbound-system generic connect-token \
Log into the Helm OCI registry using your license token:

```bash
jq -r .token $SPACES_TOKEN_PATH | helm registry login xpkg.upbound.io \
--username upbound --password-stdin
jq -r .token $SPACES_TOKEN_PATH | helm registry login xpkg.upbound.io -u $(jq -r .accessId $SPACES_TOKEN_PATH) --password-stdin
```

Install the connect agent:

```bash
helm -n upbound-system upgrade --install agent \
oci://xpkg.upbound.io/spaces-artifacts/agent \
--set "imagePullSecrets[0].name=upbound-pull-secret" \
--version "0.0.0-1116.g14cbfe6" \
--set "global.space=${UPBOUND_SPACE_NAME}" \
--set "global.organization=${UPBOUND_ORG_NAME}" \
--set "global.tokenSecret=connect-token" \
--set "image.repository=xpkg.upbound.io/spaces-artifacts/agent" \
--set "registration.image.repository=xpkg.upbound.io/spaces-artifacts/register-init" \
--set "registration.enabled=true" \
--set "space=${UPBOUND_SPACE_NAME}" \
--set "organization=${UPBOUND_ORG_NAME}" \
--set "tokenSecret=connect-token" \
--set "imagePullSecrets[0].name=upbound-pull-secret" \
--set "billing.enabled=false" \
--wait
```

Expand Down
59 changes: 54 additions & 5 deletions self-hosted-spaces_versioned_docs/version-1.15/howtos/attach-detach.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,14 +81,63 @@ In the same cluster where you installed the Spaces software, install the Upbound
```bash
helm -n upbound-system upgrade --install agent \
oci://xpkg.upbound.io/spaces-artifacts/agent \
--version "0.0.0-441.g68777b9" \
--version "0.0.0-1116.g14cbfe6" \
--set "global.space=${UPBOUND_SPACE_NAME}" \
--set "global.organization=${UPBOUND_ORG_NAME}" \
--set "global.tokenSecret=connect-token" \
--set "image.repository=xpkg.upbound.io/spaces-artifacts/agent" \
--set "registration.image.repository=xpkg.upbound.io/spaces-artifacts/register-init" \
--set "registration.enabled=true" \
--set "imagePullSecrets[0].name=upbound-pull-secret" \
--set "billing.enabled=false" \
--wait
```

#### Use an HTTP proxy

The Connect agent respects `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` for outbound traffic to Upbound. Set them on the agent with `extraEnv` and on the registration init container with `registration.extraEnv`. If you use Zscaler or a similar corporate forward proxy, use the same pattern for both as shown below.

| Variable | Description |
| --- | --- |
| `HTTP_PROXY` | HTTP proxy URL |
| `HTTPS_PROXY` | HTTPS proxy URL |
| `NO_PROXY` | Comma-separated hosts that bypass the proxy |

Example `agent-proxy-values.yaml`:

```yaml
extraEnv:
- name: HTTP_PROXY
value: "http://proxy.example.com:8080"
- name: HTTPS_PROXY
value: "http://proxy.example.com:8080"
- name: NO_PROXY
value: "10.0.0.0/8,.svc.cluster.local,localhost,127.0.0.1"
registration:
extraEnv:
- name: HTTP_PROXY
value: "http://proxy.example.com:8080"
- name: HTTPS_PROXY
value: "http://proxy.example.com:8080"
- name: NO_PROXY
value: "10.0.0.0/8,.svc.cluster.local,localhost,127.0.0.1"
```

Install or upgrade using that file:

```bash
helm -n upbound-system upgrade --install agent \
oci://xpkg.upbound.io/spaces-artifacts/agent \
--version "0.0.0-1116.g14cbfe6" \
--set "global.space=${UPBOUND_SPACE_NAME}" \
--set "global.organization=${UPBOUND_ORG_NAME}" \
--set "global.tokenSecret=connect-token" \
--set "image.repository=xpkg.upbound.io/spaces-artifacts/agent" \
--set "registration.image.repository=xpkg.upbound.io/spaces-artifacts/register-init" \
--set "registration.enabled=true" \
--set "space=${UPBOUND_SPACE_NAME}" \
--set "organization=${UPBOUND_ORG_NAME}" \
--set "tokenSecret=connect-token" \
--set "imagePullSecrets[0].name=upbound-pull-secret" \
--set "billing.enabled=false" \
-f agent-proxy-values.yaml \
--wait
```

Expand Down Expand Up @@ -173,7 +222,7 @@ Users interact with the Upbound Console to generate request queries to the Upbou

:::important
This data only concerns resource configuration. The data _inside_ the managed
resource in your Space isn't visible at any point.
resource in your Space isn't visible at any point.
:::

**Upbound can't see your data.** Upbound doesn't have access to session-based data rendered for your users in the Upbound Console. Upbound has no information about your self-hosted Space, other than that you've connected a self-hosted Space.
Expand Down
17 changes: 10 additions & 7 deletions self-hosted-spaces_versioned_docs/version-1.15/self-hosted-spaces-quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -185,7 +185,7 @@ up robot create "${UPBOUND_SPACE_NAME}" --description="Robot used for connect ag
export UPBOUND_TOKEN=$(up robot token create "${UPBOUND_SPACE_NAME}" "${UPBOUND_SPACE_NAME}-token" -ojson | jq -r .token)
```

Create a Kubernetes secret from the token:
Create a secret containing the robot token:

```bash
kubectl create secret -n upbound-system generic connect-token \
Expand All @@ -195,20 +195,23 @@ kubectl create secret -n upbound-system generic connect-token \
Log into the Helm OCI registry using your license token:

```bash
jq -r .token $SPACES_TOKEN_PATH | helm registry login xpkg.upbound.io \
--username upbound --password-stdin
jq -r .token $SPACES_TOKEN_PATH | helm registry login xpkg.upbound.io -u $(jq -r .accessId $SPACES_TOKEN_PATH) --password-stdin
```

Install the connect agent:

```bash
helm -n upbound-system upgrade --install agent \
oci://xpkg.upbound.io/spaces-artifacts/agent \
--set "imagePullSecrets[0].name=upbound-pull-secret" \
--version "0.0.0-1116.g14cbfe6" \
--set "global.space=${UPBOUND_SPACE_NAME}" \
--set "global.organization=${UPBOUND_ORG_NAME}" \
--set "global.tokenSecret=connect-token" \
--set "image.repository=xpkg.upbound.io/spaces-artifacts/agent" \
--set "registration.image.repository=xpkg.upbound.io/spaces-artifacts/register-init" \
--set "registration.enabled=true" \
--set "space=${UPBOUND_SPACE_NAME}" \
--set "organization=${UPBOUND_ORG_NAME}" \
--set "tokenSecret=connect-token" \
--set "imagePullSecrets[0].name=upbound-pull-secret" \
--set "billing.enabled=false" \
--wait
```

Expand Down
Loading
Loading