diff --git a/cloud-spaces-docs/howtos/api-connector.md b/cloud-spaces-docs/howtos/api-connector.md deleted file mode 100644 index 87594dec..00000000 --- a/cloud-spaces-docs/howtos/api-connector.md +++ /dev/null @@ -1,409 +0,0 @@ ---- -title: API Connector -weight: 90 -description: Connect Kubernetes clusters to remote Crossplane control planes for resource synchronization -draft: true -aliases: - - /api-connector - - /concepts/api-connector ---- - -:::warning -API Connector is currently in **Preview**. The feature is under active -development and subject to breaking changes. Use for testing and evaluation -purposes only. -::: - -API Connector enables seamless integration between Kubernetes application -clusters consuming APIs and remote Crossplane control planes providing and -reconciling APIs. - -You can use the API Connector to decouple where Crossplane is running (for -example in an Upbound control plane), and where APIs are consumed -(for example in an existing Kubernetes cluster). This gives you flexibility and -consistency in your control plane operations. - - - -Unlike the [Control Plane Connector](ctp-connector.md) which offers only -coarse-grained connectivity between app clusters and a control plane, API -connector offers fine-grained configuration of which APIs get offered along with -multi-cluster connectivity. - -## Architecture overview - -![API Connector Architecture](/img/api-connector.png) - -API Connector uses a **provider-consumer** model: - -- **Provider control plane**: The Upbound control plane that provides APIs and manages infrastructure. -- **Consumer cluster**: Any Kubernetes cluster where its users wants to use APIs provided by the provider control plane, without having to run Crossplane. API connector gets installed in the consumer cluster, and bidirectionally syncs API objects to the provider. - -### Key components - -**Custom Resource Definitions (CRDs)**: - - -- `ClusterConnection`: Establishes a connection from the consumer to the provider cluster. Pulls bindable CRD APIs from the provider into the consumer cluster for use. - -- `ClusterAPIBinding`: Instructs API connector to sync all API objects cluster-wide with a given API group to a given provider cluster. -- `APIBinding`: Namespaced version of `ClusterAPIBinding`. Instructs API connector to sync API objects within a given namespace and with a given API group to a given provider cluster. - - -## Prerequisites - -Before using API Connector, ensure: - -1. **Consumer cluster** has network access to the provider control plane -1. You have an license to use API connector. If you are unsure, [contact Upbound][contact] or your sales representative. - -This guide walks through how to automate connecting your cluster to an Upbound -control plane. You can also manually configure the API Connector. - -## Publishing APIs in the provider cluster - - - - -First, log in to your provider control plane, and choose which CRD APIs you want -to make accessible to the consumer cluster's. API connector only syncs -these "bindable" CRDs. - - - - - - -Use the `up` CLI to login: - -```bash -up login -``` - -Connect to your control plane: - -```bash -up ctx -``` - -Check what CRDs are available: - -```bash -kubectl get crds -``` - - -Label all CRDs you want to publish with the bindable label: - - -```bash -kubectl label crd 'connect.upbound.io/bindable'='true' --overwrite -``` - - - - -Change context to the provider cluster: -```bash -kubectl config set-context -``` - -Check what CRDs are available: -```bash -kubectl get crds -``` - - -Label all CRDs you want to publish with the bindable label - -```bash -kubectl label crd 'connect.upbound.io/bindable'='true' --overwrite -``` - - - -## Installation - - - - -The up CLI provides the simplest installation method with automatic -configuration: - -Make sure the current Kubeconfig context is set to the **provider control plane** -```bash -up ctx - -up controlplane api-connector install --consumer-kubeconfig [OPTIONS] -``` - -The command: -1. creates a Robot account (named ``) in the Upbound Cloud organization ``, -1. Gives the created robot account `admin` permissions to the provider control plane `` -1. Generates a JWT token for the robot account, and stores it in a Kubernetes Secret in the consumer cluster. -1. Installs the API connector Helm chart in the consumer cluster. -1. Creates a `ClusterConnection` object in the consumer cluster, referring to the newly generated Secret, so that API connector can authenticate successfully to the provider control plane. -1. API connector pulls all published CRDs from the previous step into the consumer cluster. - -**Example**: -```bash -up controlplane api-connector install \ - --consumer-kubeconfig ~/.kube/config \ - --consumer-context my-cluster \ - --upbound-token -``` - -This command uses provided token to authenticate with the **Provider control plane** -and create a `ClusterConnection` resource in the **Consumer cluster** to connect to the -**Provider control plane**. - -**Key Options**: -- `--consumer-kubeconfig`: Path to consumer cluster kubeconfig (required) -- `--consumer-context`: Context name for consumer cluster (required) -- `--name`: Custom name for connection resources (optional) -- `--upbound-token`: API token for authentication (optional) -- `--upgrade`: Upgrade existing installation (optional) -- `--version`: Specific version to install (optional) - - - - -For manual installation or custom configurations: - -```bash -helm upgrade --install api-connector oci://xpkg.upbound.io/spaces-artifacts/api-connector \ - --namespace upbound-system \ - --create-namespace \ - --version \ - --set consumerClusterDisplayName= -``` - -### Authentication methods - -API Connector supports two authentication methods: - - - - -For Upbound Spaces integration: - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: spaces-secret - namespace: upbound-system -type: Opaque -stringData: - token: - organization: - spacesBaseURL: - controlPlaneGroupName: - controlPlaneName: -``` - - - -For direct cluster access: - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: provider-kubeconfig - namespace: upbound-system -type: Opaque -data: - kubeconfig: -``` - - - - -### Connection setup - -Create a `ClusterConnection` to establish connectivity: - - - - -```yaml -apiVersion: connect.upbound.io/v1alpha1 -kind: ClusterConnection -metadata: - name: spaces-connection - namespace: upbound-system -spec: - secretRef: - kind: UpboundRobotToken - name: spaces-secret - namespace: upbound-system - crdManagement: - pullBehavior: Pull -``` - - - - -```yaml -apiVersion: connect.upbound.io/v1alpha1 -kind: ClusterConnection -metadata: - name: provider-connection - namespace: upbound-system -spec: - secretRef: - kind: KubeConfig - name: provider-kubeconfig - namespace: upbound-system - crdManagement: - pullBehavior: Pull -``` - - - - - - - -### Configuration - -Bind APIs to make them available in your consumer cluster: - -```yaml -apiVersion: connect.upbound.io/v1alpha1 -kind: ClusterAPIBinding -metadata: - name: -spec: - connectionRef: - kind: ClusterConnection - name: # Or --name value -``` - - - - -The `ClusterAPIBinding` name must match the **Resource.Group** (name of the CustomResourceDefinition) of the CRD you want to bind. - - - - -## Usage example - -After configuration, you can create API objects (in the consumer cluster) that -will be synchronized to the provider cluster: - -```yaml -apiVersion: nop.example.org/v1alpha1 -kind: NopResource -metadata: - name: my-resource - namespace: default -spec: - coolField: "Synchronized resource" - compositeDeletePolicy: Foreground -``` - -Verify the resource status: - -```bash -kubectl get nopresource my-resource -o yaml - -``` -When the `APIBound=True` condition is present, it means that the API object has -been synced to the provider cluster, and is being reconciled there. Whenever the -API object in the provider cluster gets status updates (for example -`Ready=True`), that status is synced back to the consumer cluster. - -Switch contexts to the provider cluster to see the API object being created: - -```bash -up ctx -# or kubectl config set-context -``` - -```bash -kubectl get nopresource my-resource -o yaml -``` - -Note that in the provider cluster, the API object is labeled with information on -where the API object originates from, and `connect.upbound.io/managed=true`. - -## Monitoring and troubleshooting - -### Check connection status - -```bash -kubectl get clusterconnection -``` - -Expected output: -``` -NAME STATUS MESSAGE -spaces-connection Ready Provider controlplane is available -``` - -### View available APIs - -```bash -kubectl get clusterconnection spaces-connection -o jsonpath='{.status.offeredAPIs[*].name}' -``` - -### Check API binding status - -```bash -kubectl get clusterapibinding -``` - -### Debug resource synchronization - -```bash -kubectl describe -``` - -## Removal - -### Using the up CLI - -```bash -up controlplane api-connector uninstall \ - --consumer-kubeconfig ~/.kube/config \ - --all -``` - -The `--all` flag removes all resources including connections and secrets. -Without the flag, only runtime related resources won't be removed. - -:::note -Uninstall doesn't remove any API objects in the provider control plane. If you -want to clean up all API objects there, delete all API objects from the consumer -cluster before API connector uninstallation, and wait for the objects to get -deleted. -::: - - -### Using Helm - -```bash -helm uninstall api-connector -n upbound-system -``` - -## Limitations - -- **Preview feature**: Subject to breaking changes. Not yet production grade. -- **CRD updates**: CRDs are pulled once but not automatically updated. If multiple Crossplane clusters offer the same CRD API, API changes must be synchronized out of band, for example using a [Crossplane Configuration](https://docs.crossplane.io/latest/packages/). -- **Network requirements**: Consumer cluster must have direct network access to provider cluster. -- **Wide permissions needed in consumer cluster**: Because the API connector doesn't know up front the names of the APIs it needs to reconcile, it currently runs with full "root" privileges in the consumer cluster. - -- **Connector polling**: API Connector checks for drift between the consumer and provider cluster - periodically through polling. The poll interval can be changed with the `pollInterval` Helm value. - - -## Advanced configuration - -### Multiple connections - -You can connect to multiple provider clusters simultaneously by creating multiple `ClusterConnection` resources with different names and configurations. - -[contact]: https://www.upbound.io/contact-us diff --git a/cloud-spaces-docs/howtos/mcp-connector-guide.md b/cloud-spaces-docs/howtos/mcp-connector-guide.md index c75b0798..1046d598 100644 --- a/cloud-spaces-docs/howtos/mcp-connector-guide.md +++ b/cloud-spaces-docs/howtos/mcp-connector-guide.md @@ -161,4 +161,3 @@ In this tutorial, you: [control-plane-connector]: /cloud-spaces/howtos/ctp-connector [platform-reference-configuration]: https://marketplace.upbound.io/configurations/upbound/platform-ref-aws -[api-connector]: /cloud-spaces/howtos/api-connector diff --git a/docs/reference/cli-reference.md b/docs/reference/cli-reference.md index bfcef8dd..a60b24a2 100644 --- a/docs/reference/cli-reference.md +++ b/docs/reference/cli-reference.md @@ -22,9 +22,6 @@ import UpConfigSet from '/cli/up_config_set.md'; import UpControlplane from '/cli/up_controlplane.md'; import UpControlplaneAddOn from '/cli/up_controlplane_add-on.md'; import UpControlplaneAddOnInstall from '/cli/up_controlplane_add-on_install.md'; -import UpControlplaneAPIConnector from '/cli/up_controlplane_api-connector.md'; -import UpControlplaneAPIConnectorInstall from '/cli/up_controlplane_api-connector_install.md'; -import UpControlplaneAPIConnectorUninstall from '/cli/up_controlplane_api-connector_uninstall.md'; import UpControlplaneConfiguration from '/cli/up_controlplane_configuration.md'; import UpControlplaneConfigurationInstall from '/cli/up_controlplane_configuration_install.md'; import UpControlplaneConnector from '/cli/up_controlplane_connector.md'; @@ -226,15 +223,6 @@ import UpXrdGenerate from '/cli/up_xrd_generate.md'; ## up controlplane add-on install -## up controlplane api-connector - - -## up controlplane api-connector install - - -## up controlplane api-connector uninstall - - ## up controlplane configuration diff --git a/self-hosted-spaces-docs/howtos/api-connector.md b/self-hosted-spaces-docs/howtos/api-connector.md deleted file mode 100644 index 20ca757d..00000000 --- a/self-hosted-spaces-docs/howtos/api-connector.md +++ /dev/null @@ -1,408 +0,0 @@ ---- -title: API Connector -weight: 90 -description: Connect Kubernetes clusters to remote Crossplane control planes for resource synchronization -aliases: - - /api-connector - - /concepts/api-connector ---- - -:::warning -API Connector is currently in **Preview**. The feature is under active -development and subject to breaking changes. Use for testing and evaluation -purposes only. -::: - -API Connector enables seamless integration between Kubernetes application -clusters consuming APIs and remote Crossplane control planes providing and -reconciling APIs. - - -The API Connector decouples where Crossplane runs from where teams consume its -APIs. For example, Crossplane may run in an Upbound control plane while an -existing Kubernetes cluster consumes its APIs. - -The Control Plane Connector offers coarse-grained connectivity between app -clusters and a control plane. The API Connector lets you choose -which APIs to expose across multiple clusters. - -## Architecture overview - -![API Connector Architecture](/img/api-connector.png) - -API Connector uses a **provider-consumer** model: - -- **Provider control plane**: The Upbound control plane that provides APIs and manages infrastructure. -- **Consumer cluster**: Any Kubernetes cluster where its users wants to use APIs provided by the provider control plane, without having to run Crossplane. API connector gets installed in the consumer cluster, and bidirectionally syncs API objects to the provider. - -### Key components - -**Custom Resource Definitions (CRDs)**: - - -- `ClusterConnection`: Establishes a connection from the consumer to the provider cluster. Pulls bindable CRD APIs from the provider into the consumer cluster for use. - -- `ClusterAPIBinding`: Instructs API connector to sync all API objects cluster-wide with a given API group to a given provider cluster. -- `APIBinding`: Namespaced version of `ClusterAPIBinding`. Instructs API connector to sync API objects within a given namespace and with a given API group to a given provider cluster. - - -## Prerequisites - -Before using API Connector, ensure: - -1. **Consumer cluster** has network access to the provider control plane -1. You have an license to use API connector. If you are unsure, [contact Upbound][contact] or your sales representative. - -This guide walks through how to automate connecting your cluster to an Upbound -control plane. You can also manually configure the API Connector. - -## Publishing APIs in the provider cluster - - - - -First, log in to your provider control plane, and choose which CRD APIs you want -to make accessible to the consumer cluster's. API connector only syncs -these "bindable" CRDs. - - - - - - -Use the `up` CLI to login: - -```bash -up login -``` - -Connect to your control plane: - -```bash -up ctx -``` - -Check what CRDs are available: - -```bash -kubectl get crds -``` - - -Label all CRDs you want to publish with the bindable label: - - -```bash -kubectl label crd 'connect.upbound.io/bindable'='true' --overwrite -``` - - - - -Change context to the provider cluster: -```bash -kubectl config set-context -``` - -Check what CRDs are available: -```bash -kubectl get crds -``` - - -Label all CRDs you want to publish with the bindable label - -```bash -kubectl label crd 'connect.upbound.io/bindable'='true' --overwrite -``` - - - -## Installation - - - - -The up CLI provides the simplest installation method with automatic -configuration: - -Make sure the current Kubeconfig context is set to the **provider control plane** -```bash -up ctx - -up controlplane api-connector install --consumer-kubeconfig [OPTIONS] -``` - -The command: -1. creates a Robot account (named ``) in the Upbound Cloud organization ``, -1. Gives the created robot account `admin` permissions to the provider control plane `` -1. Generates a JWT token for the robot account, and stores it in a Kubernetes Secret in the consumer cluster. -1. Installs the API connector Helm chart in the consumer cluster. -1. Creates a `ClusterConnection` object in the consumer cluster, referring to the newly generated Secret, so that API connector can authenticate successfully to the provider control plane. -1. API connector pulls all published CRDs from the previous step into the consumer cluster. - -**Example**: -```bash -up controlplane api-connector install \ - --consumer-kubeconfig ~/.kube/config \ - --consumer-context my-cluster \ - --upbound-token -``` - -This command uses provided token to authenticate with the **Provider control plane** -and create a `ClusterConnection` resource in the **Consumer cluster** to connect to the -**Provider control plane**. - -**Key Options**: -- `--consumer-kubeconfig`: Path to consumer cluster kubeconfig (required) -- `--consumer-context`: Context name for consumer cluster (required) -- `--name`: Custom name for connection resources (optional) -- `--upbound-token`: API token for authentication (optional) -- `--upgrade`: Upgrade existing installation (optional) -- `--version`: Specific version to install (optional) - - - - -For manual installation or custom configurations: - -```bash -helm upgrade --install api-connector oci://xpkg.upbound.io/spaces-artifacts/api-connector \ - --namespace upbound-system \ - --create-namespace \ - --version \ - --set consumerClusterDisplayName= -``` - -### Authentication methods - -API Connector supports two authentication methods: - - - - -For Upbound Spaces integration: - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: spaces-secret - namespace: upbound-system -type: Opaque -stringData: - token: - organization: - spacesBaseURL: - controlPlaneGroupName: - controlPlaneName: -``` - - - -For direct cluster access: - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: provider-kubeconfig - namespace: upbound-system -type: Opaque -data: - kubeconfig: -``` - - - - -### Connection setup - -Create a `ClusterConnection` to establish connectivity: - - - - -```yaml -apiVersion: connect.upbound.io/v1alpha1 -kind: ClusterConnection -metadata: - name: spaces-connection - namespace: upbound-system -spec: - secretRef: - kind: UpboundRobotToken - name: spaces-secret - namespace: upbound-system - crdManagement: - pullBehavior: Pull -``` - - - - -```yaml -apiVersion: connect.upbound.io/v1alpha1 -kind: ClusterConnection -metadata: - name: provider-connection - namespace: upbound-system -spec: - secretRef: - kind: KubeConfig - name: provider-kubeconfig - namespace: upbound-system - crdManagement: - pullBehavior: Pull -``` - - - - - - - -### Configuration - -Bind APIs to make them available in your consumer cluster: - -```yaml -apiVersion: connect.upbound.io/v1alpha1 -kind: ClusterAPIBinding -metadata: - name: -spec: - connectionRef: - kind: ClusterConnection - name: # Or --name value -``` - - - - -The `ClusterAPIBinding` name must match the **Resource.Group** (name of the CustomResourceDefinition) of the CRD you want to bind. - - - - -## Usage example - -After configuration, you can create API objects (in the consumer cluster) to -synchronize to the provider cluster: - -```yaml -apiVersion: nop.example.org/v1alpha1 -kind: NopResource -metadata: - name: my-resource - namespace: default -spec: - coolField: "Synchronized resource" - compositeDeletePolicy: Foreground -``` - -Verify the resource status: - -```bash -kubectl get nopresource my-resource -o yaml - -``` -When the `APIBound=True` condition is present, it means that the API object -synced to the provider cluster, where reconciliation occurs. Whenever the -API object in the provider cluster gets status updates (for example -`Ready=True`), that status syncs back to the consumer cluster. - - -Switch contexts to the provider cluster to see the API object being created: - -```bash -up ctx -# or kubectl config set-context -``` - -```bash -kubectl get nopresource my-resource -o yaml -``` - -Note that in the provider cluster, the API object is labeled with information on -where the API object originates from, and `connect.upbound.io/managed=true`. - -## Monitoring and troubleshooting - -### Check connection status - -```bash -kubectl get clusterconnection -``` - -Expected output: -``` -NAME STATUS MESSAGE -spaces-connection Ready Provider controlplane is available -``` - -### View available APIs - -```bash -kubectl get clusterconnection spaces-connection -o jsonpath='{.status.offeredAPIs[*].name}' -``` - -### Check API binding status - -```bash -kubectl get clusterapibinding -``` - -### Debug resource synchronization - -```bash -kubectl describe -``` - -## Removal - -### Using the up CLI - -```bash -up controlplane api-connector uninstall \ - --consumer-kubeconfig ~/.kube/config \ - --all -``` - -The `--all` flag removes all resources including connections and secrets. -Without the flag, runtime related resources persist. - -:::note -Uninstall doesn't remove any API objects in the provider control plane. -To clean all API objects, delete all API objects from the consumer -cluster before API connector uninstallation, and wait for the objects to get -deleted. -::: - - -### Using Helm - -```bash -helm uninstall api-connector -n upbound-system -``` - - -## Limitations - - -- **Preview feature**: Subject to breaking changes. Not yet production grade. -- **CRD updates**: CRDs are pulled once but not automatically updated. If multiple Crossplane clusters offer the same CRD API, API changes must be synchronized out of band, for example using a [Crossplane Configuration](https://docs.crossplane.io/latest/packages/). -- **Network requirements**: Consumer cluster must have direct network access to provider cluster. -- **Wide permissions needed in consumer cluster**: Because the API connector doesn't know up front the names of the APIs it needs to reconcile, it currently runs with full "root" privileges in the consumer cluster. - -- **Connector polling**: API Connector checks for drift between the consumer and provider cluster - periodically through polling. The poll interval can be changed with the `pollInterval` Helm value. - - -## Advanced configuration - -### Multiple connections - -You can connect to multiple provider clusters simultaneously by creating multiple `ClusterConnection` resources with different names and configurations. - -[contact]: https://www.upbound.io/contact-us diff --git a/self-hosted-spaces-docs/howtos/mcp-connector-guide.md b/self-hosted-spaces-docs/howtos/mcp-connector-guide.md index f7b3906c..10f1e9b4 100644 --- a/self-hosted-spaces-docs/howtos/mcp-connector-guide.md +++ b/self-hosted-spaces-docs/howtos/mcp-connector-guide.md @@ -161,4 +161,3 @@ In this tutorial, you: [control-plane-connector]: /self-hosted-spaces/howtos/ctp-connector [platform-reference-configuration]: https://marketplace.upbound.io/configurations/upbound/platform-ref-aws -[api-connector]: /self-hosted-spaces/howtos/api-connector diff --git a/self-hosted-spaces_versioned_docs/version-1.13/howtos/api-connector.md b/self-hosted-spaces_versioned_docs/version-1.13/howtos/api-connector.md deleted file mode 100644 index 4db30bac..00000000 --- a/self-hosted-spaces_versioned_docs/version-1.13/howtos/api-connector.md +++ /dev/null @@ -1,408 +0,0 @@ ---- -title: API Connector -weight: 90 -description: Connect Kubernetes clusters to remote Crossplane control planes for resource synchronization -aliases: - - /api-connector - - /concepts/api-connector ---- - -:::warning -API Connector is currently in **Preview**. The feature is under active -development and subject to breaking changes. Use for testing and evaluation -purposes only. -::: - -API Connector enables seamless integration between Kubernetes application -clusters consuming APIs and remote Crossplane control planes providing and -reconciling APIs. - -You can use the API Connector to decouple where Crossplane is running (for -example in an Upbound control plane), and where APIs are consumed -(for example in an existing Kubernetes cluster). This gives you flexibility and -consistency in your control plane operations. - - - -Unlike the [Control Plane Connector](ctp-connector.md) which offers only -coarse-grained connectivity between app clusters and a control plane, API -connector offers fine-grained configuration of which APIs get offered along with -multi-cluster connectivity. - -## Architecture overview - -![API Connector Architecture](/img/api-connector.png) - -API Connector uses a **provider-consumer** model: - -- **Provider control plane**: The Upbound control plane that provides APIs and manages infrastructure. -- **Consumer cluster**: Any Kubernetes cluster where its users wants to use APIs provided by the provider control plane, without having to run Crossplane. API connector gets installed in the consumer cluster, and bidirectionally syncs API objects to the provider. - -### Key components - -**Custom Resource Definitions (CRDs)**: - - -- `ClusterConnection`: Establishes a connection from the consumer to the provider cluster. Pulls bindable CRD APIs from the provider into the consumer cluster for use. - -- `ClusterAPIBinding`: Instructs API connector to sync all API objects cluster-wide with a given API group to a given provider cluster. -- `APIBinding`: Namespaced version of `ClusterAPIBinding`. Instructs API connector to sync API objects within a given namespace and with a given API group to a given provider cluster. - - -## Prerequisites - -Before using API Connector, ensure: - -1. **Consumer cluster** has network access to the provider control plane -1. You have an license to use API connector. If you are unsure, [contact Upbound][contact] or your sales representative. - -This guide walks through how to automate connecting your cluster to an Upbound -control plane. You can also manually configure the API Connector. - -## Publishing APIs in the provider cluster - - - - -First, log in to your provider control plane, and choose which CRD APIs you want -to make accessible to the consumer cluster's. API connector only syncs -these "bindable" CRDs. - - - - - - -Use the `up` CLI to login: - -```bash -up login -``` - -Connect to your control plane: - -```bash -up ctx -``` - -Check what CRDs are available: - -```bash -kubectl get crds -``` - - -Label all CRDs you want to publish with the bindable label: - - -```bash -kubectl label crd 'connect.upbound.io/bindable'='true' --overwrite -``` - - - - -Change context to the provider cluster: -```bash -kubectl config set-context -``` - -Check what CRDs are available: -```bash -kubectl get crds -``` - - -Label all CRDs you want to publish with the bindable label - -```bash -kubectl label crd 'connect.upbound.io/bindable'='true' --overwrite -``` - - - -## Installation - - - - -The up CLI provides the simplest installation method with automatic -configuration: - -Make sure the current Kubeconfig context is set to the **provider control plane** -```bash -up ctx - -up controlplane api-connector install --consumer-kubeconfig [OPTIONS] -``` - -The command: -1. creates a Robot account (named ``) in the Upbound Cloud organization ``, -1. Gives the created robot account `admin` permissions to the provider control plane `` -1. Generates a JWT token for the robot account, and stores it in a Kubernetes Secret in the consumer cluster. -1. Installs the API connector Helm chart in the consumer cluster. -1. Creates a `ClusterConnection` object in the consumer cluster, referring to the newly generated Secret, so that API connector can authenticate successfully to the provider control plane. -1. API connector pulls all published CRDs from the previous step into the consumer cluster. - -**Example**: -```bash -up controlplane api-connector install \ - --consumer-kubeconfig ~/.kube/config \ - --consumer-context my-cluster \ - --upbound-token -``` - -This command uses provided token to authenticate with the **Provider control plane** -and create a `ClusterConnection` resource in the **Consumer cluster** to connect to the -**Provider control plane**. - -**Key Options**: -- `--consumer-kubeconfig`: Path to consumer cluster kubeconfig (required) -- `--consumer-context`: Context name for consumer cluster (required) -- `--name`: Custom name for connection resources (optional) -- `--upbound-token`: API token for authentication (optional) -- `--upgrade`: Upgrade existing installation (optional) -- `--version`: Specific version to install (optional) - - - - -For manual installation or custom configurations: - -```bash -helm upgrade --install api-connector oci://xpkg.upbound.io/spaces-artifacts/api-connector \ - --namespace upbound-system \ - --create-namespace \ - --version \ - --set consumerClusterDisplayName= -``` - -### Authentication methods - -API Connector supports two authentication methods: - - - - -For Upbound Spaces integration: - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: spaces-secret - namespace: upbound-system -type: Opaque -stringData: - token: - organization: - spacesBaseURL: - controlPlaneGroupName: - controlPlaneName: -``` - - - -For direct cluster access: - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: provider-kubeconfig - namespace: upbound-system -type: Opaque -data: - kubeconfig: -``` - - - - -### Connection setup - -Create a `ClusterConnection` to establish connectivity: - - - - -```yaml -apiVersion: connect.upbound.io/v1alpha1 -kind: ClusterConnection -metadata: - name: spaces-connection - namespace: upbound-system -spec: - secretRef: - kind: UpboundRobotToken - name: spaces-secret - namespace: upbound-system - crdManagement: - pullBehavior: Pull -``` - - - - -```yaml -apiVersion: connect.upbound.io/v1alpha1 -kind: ClusterConnection -metadata: - name: provider-connection - namespace: upbound-system -spec: - secretRef: - kind: KubeConfig - name: provider-kubeconfig - namespace: upbound-system - crdManagement: - pullBehavior: Pull -``` - - - - - - - -### Configuration - -Bind APIs to make them available in your consumer cluster: - -```yaml -apiVersion: connect.upbound.io/v1alpha1 -kind: ClusterAPIBinding -metadata: - name: -spec: - connectionRef: - kind: ClusterConnection - name: # Or --name value -``` - - - - -The `ClusterAPIBinding` name must match the **Resource.Group** (name of the CustomResourceDefinition) of the CRD you want to bind. - - - - -## Usage example - -After configuration, you can create API objects (in the consumer cluster) that -will be synchronized to the provider cluster: - -```yaml -apiVersion: nop.example.org/v1alpha1 -kind: NopResource -metadata: - name: my-resource - namespace: default -spec: - coolField: "Synchronized resource" - compositeDeletePolicy: Foreground -``` - -Verify the resource status: - -```bash -kubectl get nopresource my-resource -o yaml - -``` -When the `APIBound=True` condition is present, it means that the API object has -been synced to the provider cluster, and is being reconciled there. Whenever the -API object in the provider cluster gets status updates (for example -`Ready=True`), that status is synced back to the consumer cluster. - -Switch contexts to the provider cluster to see the API object being created: - -```bash -up ctx -# or kubectl config set-context -``` - -```bash -kubectl get nopresource my-resource -o yaml -``` - -Note that in the provider cluster, the API object is labeled with information on -where the API object originates from, and `connect.upbound.io/managed=true`. - -## Monitoring and troubleshooting - -### Check connection status - -```bash -kubectl get clusterconnection -``` - -Expected output: -``` -NAME STATUS MESSAGE -spaces-connection Ready Provider controlplane is available -``` - -### View available APIs - -```bash -kubectl get clusterconnection spaces-connection -o jsonpath='{.status.offeredAPIs[*].name}' -``` - -### Check API binding status - -```bash -kubectl get clusterapibinding -``` - -### Debug resource synchronization - -```bash -kubectl describe -``` - -## Removal - -### Using the up CLI - -```bash -up controlplane api-connector uninstall \ - --consumer-kubeconfig ~/.kube/config \ - --all -``` - -The `--all` flag removes all resources including connections and secrets. -Without the flag, only runtime related resources won't be removed. - -:::note -Uninstall doesn't remove any API objects in the provider control plane. If you -want to clean up all API objects there, delete all API objects from the consumer -cluster before API connector uninstallation, and wait for the objects to get -deleted. -::: - - -### Using Helm - -```bash -helm uninstall api-connector -n upbound-system -``` - -## Limitations - -- **Preview feature**: Subject to breaking changes. Not yet production grade. -- **CRD updates**: CRDs are pulled once but not automatically updated. If multiple Crossplane clusters offer the same CRD API, API changes must be synchronized out of band, for example using a [Crossplane Configuration](https://docs.crossplane.io/latest/packages/). -- **Network requirements**: Consumer cluster must have direct network access to provider cluster. -- **Wide permissions needed in consumer cluster**: Because the API connector doesn't know up front the names of the APIs it needs to reconcile, it currently runs with full "root" privileges in the consumer cluster. - -- **Connector polling**: API Connector checks for drift between the consumer and provider cluster - periodically through polling. The poll interval can be changed with the `pollInterval` Helm value. - - -## Advanced configuration - -### Multiple connections - -You can connect to multiple provider clusters simultaneously by creating multiple `ClusterConnection` resources with different names and configurations. - -[contact]: https://www.upbound.io/contact-us diff --git a/self-hosted-spaces_versioned_docs/version-1.13/howtos/mcp-connector-guide.md b/self-hosted-spaces_versioned_docs/version-1.13/howtos/mcp-connector-guide.md index cdabb4c7..0c97cf0a 100644 --- a/self-hosted-spaces_versioned_docs/version-1.13/howtos/mcp-connector-guide.md +++ b/self-hosted-spaces_versioned_docs/version-1.13/howtos/mcp-connector-guide.md @@ -168,4 +168,3 @@ In this tutorial, you: [control-plane-connector]: /self-hosted-spaces/howtos/ctp-connector [platform-reference-configuration]: https://marketplace.upbound.io/configurations/upbound/platform-ref-aws -[api-connector]: /self-hosted-spaces/howtos/api-connector diff --git a/self-hosted-spaces_versioned_docs/version-1.14/howtos/api-connector.md b/self-hosted-spaces_versioned_docs/version-1.14/howtos/api-connector.md deleted file mode 100644 index 4db30bac..00000000 --- a/self-hosted-spaces_versioned_docs/version-1.14/howtos/api-connector.md +++ /dev/null @@ -1,408 +0,0 @@ ---- -title: API Connector -weight: 90 -description: Connect Kubernetes clusters to remote Crossplane control planes for resource synchronization -aliases: - - /api-connector - - /concepts/api-connector ---- - -:::warning -API Connector is currently in **Preview**. The feature is under active -development and subject to breaking changes. Use for testing and evaluation -purposes only. -::: - -API Connector enables seamless integration between Kubernetes application -clusters consuming APIs and remote Crossplane control planes providing and -reconciling APIs. - -You can use the API Connector to decouple where Crossplane is running (for -example in an Upbound control plane), and where APIs are consumed -(for example in an existing Kubernetes cluster). This gives you flexibility and -consistency in your control plane operations. - - - -Unlike the [Control Plane Connector](ctp-connector.md) which offers only -coarse-grained connectivity between app clusters and a control plane, API -connector offers fine-grained configuration of which APIs get offered along with -multi-cluster connectivity. - -## Architecture overview - -![API Connector Architecture](/img/api-connector.png) - -API Connector uses a **provider-consumer** model: - -- **Provider control plane**: The Upbound control plane that provides APIs and manages infrastructure. -- **Consumer cluster**: Any Kubernetes cluster where its users wants to use APIs provided by the provider control plane, without having to run Crossplane. API connector gets installed in the consumer cluster, and bidirectionally syncs API objects to the provider. - -### Key components - -**Custom Resource Definitions (CRDs)**: - - -- `ClusterConnection`: Establishes a connection from the consumer to the provider cluster. Pulls bindable CRD APIs from the provider into the consumer cluster for use. - -- `ClusterAPIBinding`: Instructs API connector to sync all API objects cluster-wide with a given API group to a given provider cluster. -- `APIBinding`: Namespaced version of `ClusterAPIBinding`. Instructs API connector to sync API objects within a given namespace and with a given API group to a given provider cluster. - - -## Prerequisites - -Before using API Connector, ensure: - -1. **Consumer cluster** has network access to the provider control plane -1. You have an license to use API connector. If you are unsure, [contact Upbound][contact] or your sales representative. - -This guide walks through how to automate connecting your cluster to an Upbound -control plane. You can also manually configure the API Connector. - -## Publishing APIs in the provider cluster - - - - -First, log in to your provider control plane, and choose which CRD APIs you want -to make accessible to the consumer cluster's. API connector only syncs -these "bindable" CRDs. - - - - - - -Use the `up` CLI to login: - -```bash -up login -``` - -Connect to your control plane: - -```bash -up ctx -``` - -Check what CRDs are available: - -```bash -kubectl get crds -``` - - -Label all CRDs you want to publish with the bindable label: - - -```bash -kubectl label crd 'connect.upbound.io/bindable'='true' --overwrite -``` - - - - -Change context to the provider cluster: -```bash -kubectl config set-context -``` - -Check what CRDs are available: -```bash -kubectl get crds -``` - - -Label all CRDs you want to publish with the bindable label - -```bash -kubectl label crd 'connect.upbound.io/bindable'='true' --overwrite -``` - - - -## Installation - - - - -The up CLI provides the simplest installation method with automatic -configuration: - -Make sure the current Kubeconfig context is set to the **provider control plane** -```bash -up ctx - -up controlplane api-connector install --consumer-kubeconfig [OPTIONS] -``` - -The command: -1. creates a Robot account (named ``) in the Upbound Cloud organization ``, -1. Gives the created robot account `admin` permissions to the provider control plane `` -1. Generates a JWT token for the robot account, and stores it in a Kubernetes Secret in the consumer cluster. -1. Installs the API connector Helm chart in the consumer cluster. -1. Creates a `ClusterConnection` object in the consumer cluster, referring to the newly generated Secret, so that API connector can authenticate successfully to the provider control plane. -1. API connector pulls all published CRDs from the previous step into the consumer cluster. - -**Example**: -```bash -up controlplane api-connector install \ - --consumer-kubeconfig ~/.kube/config \ - --consumer-context my-cluster \ - --upbound-token -``` - -This command uses provided token to authenticate with the **Provider control plane** -and create a `ClusterConnection` resource in the **Consumer cluster** to connect to the -**Provider control plane**. - -**Key Options**: -- `--consumer-kubeconfig`: Path to consumer cluster kubeconfig (required) -- `--consumer-context`: Context name for consumer cluster (required) -- `--name`: Custom name for connection resources (optional) -- `--upbound-token`: API token for authentication (optional) -- `--upgrade`: Upgrade existing installation (optional) -- `--version`: Specific version to install (optional) - - - - -For manual installation or custom configurations: - -```bash -helm upgrade --install api-connector oci://xpkg.upbound.io/spaces-artifacts/api-connector \ - --namespace upbound-system \ - --create-namespace \ - --version \ - --set consumerClusterDisplayName= -``` - -### Authentication methods - -API Connector supports two authentication methods: - - - - -For Upbound Spaces integration: - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: spaces-secret - namespace: upbound-system -type: Opaque -stringData: - token: - organization: - spacesBaseURL: - controlPlaneGroupName: - controlPlaneName: -``` - - - -For direct cluster access: - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: provider-kubeconfig - namespace: upbound-system -type: Opaque -data: - kubeconfig: -``` - - - - -### Connection setup - -Create a `ClusterConnection` to establish connectivity: - - - - -```yaml -apiVersion: connect.upbound.io/v1alpha1 -kind: ClusterConnection -metadata: - name: spaces-connection - namespace: upbound-system -spec: - secretRef: - kind: UpboundRobotToken - name: spaces-secret - namespace: upbound-system - crdManagement: - pullBehavior: Pull -``` - - - - -```yaml -apiVersion: connect.upbound.io/v1alpha1 -kind: ClusterConnection -metadata: - name: provider-connection - namespace: upbound-system -spec: - secretRef: - kind: KubeConfig - name: provider-kubeconfig - namespace: upbound-system - crdManagement: - pullBehavior: Pull -``` - - - - - - - -### Configuration - -Bind APIs to make them available in your consumer cluster: - -```yaml -apiVersion: connect.upbound.io/v1alpha1 -kind: ClusterAPIBinding -metadata: - name: -spec: - connectionRef: - kind: ClusterConnection - name: # Or --name value -``` - - - - -The `ClusterAPIBinding` name must match the **Resource.Group** (name of the CustomResourceDefinition) of the CRD you want to bind. - - - - -## Usage example - -After configuration, you can create API objects (in the consumer cluster) that -will be synchronized to the provider cluster: - -```yaml -apiVersion: nop.example.org/v1alpha1 -kind: NopResource -metadata: - name: my-resource - namespace: default -spec: - coolField: "Synchronized resource" - compositeDeletePolicy: Foreground -``` - -Verify the resource status: - -```bash -kubectl get nopresource my-resource -o yaml - -``` -When the `APIBound=True` condition is present, it means that the API object has -been synced to the provider cluster, and is being reconciled there. Whenever the -API object in the provider cluster gets status updates (for example -`Ready=True`), that status is synced back to the consumer cluster. - -Switch contexts to the provider cluster to see the API object being created: - -```bash -up ctx -# or kubectl config set-context -``` - -```bash -kubectl get nopresource my-resource -o yaml -``` - -Note that in the provider cluster, the API object is labeled with information on -where the API object originates from, and `connect.upbound.io/managed=true`. - -## Monitoring and troubleshooting - -### Check connection status - -```bash -kubectl get clusterconnection -``` - -Expected output: -``` -NAME STATUS MESSAGE -spaces-connection Ready Provider controlplane is available -``` - -### View available APIs - -```bash -kubectl get clusterconnection spaces-connection -o jsonpath='{.status.offeredAPIs[*].name}' -``` - -### Check API binding status - -```bash -kubectl get clusterapibinding -``` - -### Debug resource synchronization - -```bash -kubectl describe -``` - -## Removal - -### Using the up CLI - -```bash -up controlplane api-connector uninstall \ - --consumer-kubeconfig ~/.kube/config \ - --all -``` - -The `--all` flag removes all resources including connections and secrets. -Without the flag, only runtime related resources won't be removed. - -:::note -Uninstall doesn't remove any API objects in the provider control plane. If you -want to clean up all API objects there, delete all API objects from the consumer -cluster before API connector uninstallation, and wait for the objects to get -deleted. -::: - - -### Using Helm - -```bash -helm uninstall api-connector -n upbound-system -``` - -## Limitations - -- **Preview feature**: Subject to breaking changes. Not yet production grade. -- **CRD updates**: CRDs are pulled once but not automatically updated. If multiple Crossplane clusters offer the same CRD API, API changes must be synchronized out of band, for example using a [Crossplane Configuration](https://docs.crossplane.io/latest/packages/). -- **Network requirements**: Consumer cluster must have direct network access to provider cluster. -- **Wide permissions needed in consumer cluster**: Because the API connector doesn't know up front the names of the APIs it needs to reconcile, it currently runs with full "root" privileges in the consumer cluster. - -- **Connector polling**: API Connector checks for drift between the consumer and provider cluster - periodically through polling. The poll interval can be changed with the `pollInterval` Helm value. - - -## Advanced configuration - -### Multiple connections - -You can connect to multiple provider clusters simultaneously by creating multiple `ClusterConnection` resources with different names and configurations. - -[contact]: https://www.upbound.io/contact-us diff --git a/self-hosted-spaces_versioned_docs/version-1.14/howtos/mcp-connector-guide.md b/self-hosted-spaces_versioned_docs/version-1.14/howtos/mcp-connector-guide.md index bf658671..1c5c4b64 100644 --- a/self-hosted-spaces_versioned_docs/version-1.14/howtos/mcp-connector-guide.md +++ b/self-hosted-spaces_versioned_docs/version-1.14/howtos/mcp-connector-guide.md @@ -161,4 +161,3 @@ In this tutorial, you: [control-plane-connector]: /self-hosted-spaces/howtos/ctp-connector [platform-reference-configuration]: https://marketplace.upbound.io/configurations/upbound/platform-ref-aws -[api-connector]: /self-hosted-spaces/howtos/api-connector diff --git a/self-hosted-spaces_versioned_docs/version-1.15/howtos/api-connector.md b/self-hosted-spaces_versioned_docs/version-1.15/howtos/api-connector.md deleted file mode 100644 index 4db30bac..00000000 --- a/self-hosted-spaces_versioned_docs/version-1.15/howtos/api-connector.md +++ /dev/null @@ -1,408 +0,0 @@ ---- -title: API Connector -weight: 90 -description: Connect Kubernetes clusters to remote Crossplane control planes for resource synchronization -aliases: - - /api-connector - - /concepts/api-connector ---- - -:::warning -API Connector is currently in **Preview**. The feature is under active -development and subject to breaking changes. Use for testing and evaluation -purposes only. -::: - -API Connector enables seamless integration between Kubernetes application -clusters consuming APIs and remote Crossplane control planes providing and -reconciling APIs. - -You can use the API Connector to decouple where Crossplane is running (for -example in an Upbound control plane), and where APIs are consumed -(for example in an existing Kubernetes cluster). This gives you flexibility and -consistency in your control plane operations. - - - -Unlike the [Control Plane Connector](ctp-connector.md) which offers only -coarse-grained connectivity between app clusters and a control plane, API -connector offers fine-grained configuration of which APIs get offered along with -multi-cluster connectivity. - -## Architecture overview - -![API Connector Architecture](/img/api-connector.png) - -API Connector uses a **provider-consumer** model: - -- **Provider control plane**: The Upbound control plane that provides APIs and manages infrastructure. -- **Consumer cluster**: Any Kubernetes cluster where its users wants to use APIs provided by the provider control plane, without having to run Crossplane. API connector gets installed in the consumer cluster, and bidirectionally syncs API objects to the provider. - -### Key components - -**Custom Resource Definitions (CRDs)**: - - -- `ClusterConnection`: Establishes a connection from the consumer to the provider cluster. Pulls bindable CRD APIs from the provider into the consumer cluster for use. - -- `ClusterAPIBinding`: Instructs API connector to sync all API objects cluster-wide with a given API group to a given provider cluster. -- `APIBinding`: Namespaced version of `ClusterAPIBinding`. Instructs API connector to sync API objects within a given namespace and with a given API group to a given provider cluster. - - -## Prerequisites - -Before using API Connector, ensure: - -1. **Consumer cluster** has network access to the provider control plane -1. You have an license to use API connector. If you are unsure, [contact Upbound][contact] or your sales representative. - -This guide walks through how to automate connecting your cluster to an Upbound -control plane. You can also manually configure the API Connector. - -## Publishing APIs in the provider cluster - - - - -First, log in to your provider control plane, and choose which CRD APIs you want -to make accessible to the consumer cluster's. API connector only syncs -these "bindable" CRDs. - - - - - - -Use the `up` CLI to login: - -```bash -up login -``` - -Connect to your control plane: - -```bash -up ctx -``` - -Check what CRDs are available: - -```bash -kubectl get crds -``` - - -Label all CRDs you want to publish with the bindable label: - - -```bash -kubectl label crd 'connect.upbound.io/bindable'='true' --overwrite -``` - - - - -Change context to the provider cluster: -```bash -kubectl config set-context -``` - -Check what CRDs are available: -```bash -kubectl get crds -``` - - -Label all CRDs you want to publish with the bindable label - -```bash -kubectl label crd 'connect.upbound.io/bindable'='true' --overwrite -``` - - - -## Installation - - - - -The up CLI provides the simplest installation method with automatic -configuration: - -Make sure the current Kubeconfig context is set to the **provider control plane** -```bash -up ctx - -up controlplane api-connector install --consumer-kubeconfig [OPTIONS] -``` - -The command: -1. creates a Robot account (named ``) in the Upbound Cloud organization ``, -1. Gives the created robot account `admin` permissions to the provider control plane `` -1. Generates a JWT token for the robot account, and stores it in a Kubernetes Secret in the consumer cluster. -1. Installs the API connector Helm chart in the consumer cluster. -1. Creates a `ClusterConnection` object in the consumer cluster, referring to the newly generated Secret, so that API connector can authenticate successfully to the provider control plane. -1. API connector pulls all published CRDs from the previous step into the consumer cluster. - -**Example**: -```bash -up controlplane api-connector install \ - --consumer-kubeconfig ~/.kube/config \ - --consumer-context my-cluster \ - --upbound-token -``` - -This command uses provided token to authenticate with the **Provider control plane** -and create a `ClusterConnection` resource in the **Consumer cluster** to connect to the -**Provider control plane**. - -**Key Options**: -- `--consumer-kubeconfig`: Path to consumer cluster kubeconfig (required) -- `--consumer-context`: Context name for consumer cluster (required) -- `--name`: Custom name for connection resources (optional) -- `--upbound-token`: API token for authentication (optional) -- `--upgrade`: Upgrade existing installation (optional) -- `--version`: Specific version to install (optional) - - - - -For manual installation or custom configurations: - -```bash -helm upgrade --install api-connector oci://xpkg.upbound.io/spaces-artifacts/api-connector \ - --namespace upbound-system \ - --create-namespace \ - --version \ - --set consumerClusterDisplayName= -``` - -### Authentication methods - -API Connector supports two authentication methods: - - - - -For Upbound Spaces integration: - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: spaces-secret - namespace: upbound-system -type: Opaque -stringData: - token: - organization: - spacesBaseURL: - controlPlaneGroupName: - controlPlaneName: -``` - - - -For direct cluster access: - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: provider-kubeconfig - namespace: upbound-system -type: Opaque -data: - kubeconfig: -``` - - - - -### Connection setup - -Create a `ClusterConnection` to establish connectivity: - - - - -```yaml -apiVersion: connect.upbound.io/v1alpha1 -kind: ClusterConnection -metadata: - name: spaces-connection - namespace: upbound-system -spec: - secretRef: - kind: UpboundRobotToken - name: spaces-secret - namespace: upbound-system - crdManagement: - pullBehavior: Pull -``` - - - - -```yaml -apiVersion: connect.upbound.io/v1alpha1 -kind: ClusterConnection -metadata: - name: provider-connection - namespace: upbound-system -spec: - secretRef: - kind: KubeConfig - name: provider-kubeconfig - namespace: upbound-system - crdManagement: - pullBehavior: Pull -``` - - - - - - - -### Configuration - -Bind APIs to make them available in your consumer cluster: - -```yaml -apiVersion: connect.upbound.io/v1alpha1 -kind: ClusterAPIBinding -metadata: - name: -spec: - connectionRef: - kind: ClusterConnection - name: # Or --name value -``` - - - - -The `ClusterAPIBinding` name must match the **Resource.Group** (name of the CustomResourceDefinition) of the CRD you want to bind. - - - - -## Usage example - -After configuration, you can create API objects (in the consumer cluster) that -will be synchronized to the provider cluster: - -```yaml -apiVersion: nop.example.org/v1alpha1 -kind: NopResource -metadata: - name: my-resource - namespace: default -spec: - coolField: "Synchronized resource" - compositeDeletePolicy: Foreground -``` - -Verify the resource status: - -```bash -kubectl get nopresource my-resource -o yaml - -``` -When the `APIBound=True` condition is present, it means that the API object has -been synced to the provider cluster, and is being reconciled there. Whenever the -API object in the provider cluster gets status updates (for example -`Ready=True`), that status is synced back to the consumer cluster. - -Switch contexts to the provider cluster to see the API object being created: - -```bash -up ctx -# or kubectl config set-context -``` - -```bash -kubectl get nopresource my-resource -o yaml -``` - -Note that in the provider cluster, the API object is labeled with information on -where the API object originates from, and `connect.upbound.io/managed=true`. - -## Monitoring and troubleshooting - -### Check connection status - -```bash -kubectl get clusterconnection -``` - -Expected output: -``` -NAME STATUS MESSAGE -spaces-connection Ready Provider controlplane is available -``` - -### View available APIs - -```bash -kubectl get clusterconnection spaces-connection -o jsonpath='{.status.offeredAPIs[*].name}' -``` - -### Check API binding status - -```bash -kubectl get clusterapibinding -``` - -### Debug resource synchronization - -```bash -kubectl describe -``` - -## Removal - -### Using the up CLI - -```bash -up controlplane api-connector uninstall \ - --consumer-kubeconfig ~/.kube/config \ - --all -``` - -The `--all` flag removes all resources including connections and secrets. -Without the flag, only runtime related resources won't be removed. - -:::note -Uninstall doesn't remove any API objects in the provider control plane. If you -want to clean up all API objects there, delete all API objects from the consumer -cluster before API connector uninstallation, and wait for the objects to get -deleted. -::: - - -### Using Helm - -```bash -helm uninstall api-connector -n upbound-system -``` - -## Limitations - -- **Preview feature**: Subject to breaking changes. Not yet production grade. -- **CRD updates**: CRDs are pulled once but not automatically updated. If multiple Crossplane clusters offer the same CRD API, API changes must be synchronized out of band, for example using a [Crossplane Configuration](https://docs.crossplane.io/latest/packages/). -- **Network requirements**: Consumer cluster must have direct network access to provider cluster. -- **Wide permissions needed in consumer cluster**: Because the API connector doesn't know up front the names of the APIs it needs to reconcile, it currently runs with full "root" privileges in the consumer cluster. - -- **Connector polling**: API Connector checks for drift between the consumer and provider cluster - periodically through polling. The poll interval can be changed with the `pollInterval` Helm value. - - -## Advanced configuration - -### Multiple connections - -You can connect to multiple provider clusters simultaneously by creating multiple `ClusterConnection` resources with different names and configurations. - -[contact]: https://www.upbound.io/contact-us diff --git a/self-hosted-spaces_versioned_docs/version-1.15/howtos/mcp-connector-guide.md b/self-hosted-spaces_versioned_docs/version-1.15/howtos/mcp-connector-guide.md index bf658671..1c5c4b64 100644 --- a/self-hosted-spaces_versioned_docs/version-1.15/howtos/mcp-connector-guide.md +++ b/self-hosted-spaces_versioned_docs/version-1.15/howtos/mcp-connector-guide.md @@ -161,4 +161,3 @@ In this tutorial, you: [control-plane-connector]: /self-hosted-spaces/howtos/ctp-connector [platform-reference-configuration]: https://marketplace.upbound.io/configurations/upbound/platform-ref-aws -[api-connector]: /self-hosted-spaces/howtos/api-connector diff --git a/self-hosted-spaces_versioned_docs/version-1.16/howtos/api-connector.md b/self-hosted-spaces_versioned_docs/version-1.16/howtos/api-connector.md deleted file mode 100644 index 20ca757d..00000000 --- a/self-hosted-spaces_versioned_docs/version-1.16/howtos/api-connector.md +++ /dev/null @@ -1,408 +0,0 @@ ---- -title: API Connector -weight: 90 -description: Connect Kubernetes clusters to remote Crossplane control planes for resource synchronization -aliases: - - /api-connector - - /concepts/api-connector ---- - -:::warning -API Connector is currently in **Preview**. The feature is under active -development and subject to breaking changes. Use for testing and evaluation -purposes only. -::: - -API Connector enables seamless integration between Kubernetes application -clusters consuming APIs and remote Crossplane control planes providing and -reconciling APIs. - - -The API Connector decouples where Crossplane runs from where teams consume its -APIs. For example, Crossplane may run in an Upbound control plane while an -existing Kubernetes cluster consumes its APIs. - -The Control Plane Connector offers coarse-grained connectivity between app -clusters and a control plane. The API Connector lets you choose -which APIs to expose across multiple clusters. - -## Architecture overview - -![API Connector Architecture](/img/api-connector.png) - -API Connector uses a **provider-consumer** model: - -- **Provider control plane**: The Upbound control plane that provides APIs and manages infrastructure. -- **Consumer cluster**: Any Kubernetes cluster where its users wants to use APIs provided by the provider control plane, without having to run Crossplane. API connector gets installed in the consumer cluster, and bidirectionally syncs API objects to the provider. - -### Key components - -**Custom Resource Definitions (CRDs)**: - - -- `ClusterConnection`: Establishes a connection from the consumer to the provider cluster. Pulls bindable CRD APIs from the provider into the consumer cluster for use. - -- `ClusterAPIBinding`: Instructs API connector to sync all API objects cluster-wide with a given API group to a given provider cluster. -- `APIBinding`: Namespaced version of `ClusterAPIBinding`. Instructs API connector to sync API objects within a given namespace and with a given API group to a given provider cluster. - - -## Prerequisites - -Before using API Connector, ensure: - -1. **Consumer cluster** has network access to the provider control plane -1. You have an license to use API connector. If you are unsure, [contact Upbound][contact] or your sales representative. - -This guide walks through how to automate connecting your cluster to an Upbound -control plane. You can also manually configure the API Connector. - -## Publishing APIs in the provider cluster - - - - -First, log in to your provider control plane, and choose which CRD APIs you want -to make accessible to the consumer cluster's. API connector only syncs -these "bindable" CRDs. - - - - - - -Use the `up` CLI to login: - -```bash -up login -``` - -Connect to your control plane: - -```bash -up ctx -``` - -Check what CRDs are available: - -```bash -kubectl get crds -``` - - -Label all CRDs you want to publish with the bindable label: - - -```bash -kubectl label crd 'connect.upbound.io/bindable'='true' --overwrite -``` - - - - -Change context to the provider cluster: -```bash -kubectl config set-context -``` - -Check what CRDs are available: -```bash -kubectl get crds -``` - - -Label all CRDs you want to publish with the bindable label - -```bash -kubectl label crd 'connect.upbound.io/bindable'='true' --overwrite -``` - - - -## Installation - - - - -The up CLI provides the simplest installation method with automatic -configuration: - -Make sure the current Kubeconfig context is set to the **provider control plane** -```bash -up ctx - -up controlplane api-connector install --consumer-kubeconfig [OPTIONS] -``` - -The command: -1. creates a Robot account (named ``) in the Upbound Cloud organization ``, -1. Gives the created robot account `admin` permissions to the provider control plane `` -1. Generates a JWT token for the robot account, and stores it in a Kubernetes Secret in the consumer cluster. -1. Installs the API connector Helm chart in the consumer cluster. -1. Creates a `ClusterConnection` object in the consumer cluster, referring to the newly generated Secret, so that API connector can authenticate successfully to the provider control plane. -1. API connector pulls all published CRDs from the previous step into the consumer cluster. - -**Example**: -```bash -up controlplane api-connector install \ - --consumer-kubeconfig ~/.kube/config \ - --consumer-context my-cluster \ - --upbound-token -``` - -This command uses provided token to authenticate with the **Provider control plane** -and create a `ClusterConnection` resource in the **Consumer cluster** to connect to the -**Provider control plane**. - -**Key Options**: -- `--consumer-kubeconfig`: Path to consumer cluster kubeconfig (required) -- `--consumer-context`: Context name for consumer cluster (required) -- `--name`: Custom name for connection resources (optional) -- `--upbound-token`: API token for authentication (optional) -- `--upgrade`: Upgrade existing installation (optional) -- `--version`: Specific version to install (optional) - - - - -For manual installation or custom configurations: - -```bash -helm upgrade --install api-connector oci://xpkg.upbound.io/spaces-artifacts/api-connector \ - --namespace upbound-system \ - --create-namespace \ - --version \ - --set consumerClusterDisplayName= -``` - -### Authentication methods - -API Connector supports two authentication methods: - - - - -For Upbound Spaces integration: - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: spaces-secret - namespace: upbound-system -type: Opaque -stringData: - token: - organization: - spacesBaseURL: - controlPlaneGroupName: - controlPlaneName: -``` - - - -For direct cluster access: - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: provider-kubeconfig - namespace: upbound-system -type: Opaque -data: - kubeconfig: -``` - - - - -### Connection setup - -Create a `ClusterConnection` to establish connectivity: - - - - -```yaml -apiVersion: connect.upbound.io/v1alpha1 -kind: ClusterConnection -metadata: - name: spaces-connection - namespace: upbound-system -spec: - secretRef: - kind: UpboundRobotToken - name: spaces-secret - namespace: upbound-system - crdManagement: - pullBehavior: Pull -``` - - - - -```yaml -apiVersion: connect.upbound.io/v1alpha1 -kind: ClusterConnection -metadata: - name: provider-connection - namespace: upbound-system -spec: - secretRef: - kind: KubeConfig - name: provider-kubeconfig - namespace: upbound-system - crdManagement: - pullBehavior: Pull -``` - - - - - - - -### Configuration - -Bind APIs to make them available in your consumer cluster: - -```yaml -apiVersion: connect.upbound.io/v1alpha1 -kind: ClusterAPIBinding -metadata: - name: -spec: - connectionRef: - kind: ClusterConnection - name: # Or --name value -``` - - - - -The `ClusterAPIBinding` name must match the **Resource.Group** (name of the CustomResourceDefinition) of the CRD you want to bind. - - - - -## Usage example - -After configuration, you can create API objects (in the consumer cluster) to -synchronize to the provider cluster: - -```yaml -apiVersion: nop.example.org/v1alpha1 -kind: NopResource -metadata: - name: my-resource - namespace: default -spec: - coolField: "Synchronized resource" - compositeDeletePolicy: Foreground -``` - -Verify the resource status: - -```bash -kubectl get nopresource my-resource -o yaml - -``` -When the `APIBound=True` condition is present, it means that the API object -synced to the provider cluster, where reconciliation occurs. Whenever the -API object in the provider cluster gets status updates (for example -`Ready=True`), that status syncs back to the consumer cluster. - - -Switch contexts to the provider cluster to see the API object being created: - -```bash -up ctx -# or kubectl config set-context -``` - -```bash -kubectl get nopresource my-resource -o yaml -``` - -Note that in the provider cluster, the API object is labeled with information on -where the API object originates from, and `connect.upbound.io/managed=true`. - -## Monitoring and troubleshooting - -### Check connection status - -```bash -kubectl get clusterconnection -``` - -Expected output: -``` -NAME STATUS MESSAGE -spaces-connection Ready Provider controlplane is available -``` - -### View available APIs - -```bash -kubectl get clusterconnection spaces-connection -o jsonpath='{.status.offeredAPIs[*].name}' -``` - -### Check API binding status - -```bash -kubectl get clusterapibinding -``` - -### Debug resource synchronization - -```bash -kubectl describe -``` - -## Removal - -### Using the up CLI - -```bash -up controlplane api-connector uninstall \ - --consumer-kubeconfig ~/.kube/config \ - --all -``` - -The `--all` flag removes all resources including connections and secrets. -Without the flag, runtime related resources persist. - -:::note -Uninstall doesn't remove any API objects in the provider control plane. -To clean all API objects, delete all API objects from the consumer -cluster before API connector uninstallation, and wait for the objects to get -deleted. -::: - - -### Using Helm - -```bash -helm uninstall api-connector -n upbound-system -``` - - -## Limitations - - -- **Preview feature**: Subject to breaking changes. Not yet production grade. -- **CRD updates**: CRDs are pulled once but not automatically updated. If multiple Crossplane clusters offer the same CRD API, API changes must be synchronized out of band, for example using a [Crossplane Configuration](https://docs.crossplane.io/latest/packages/). -- **Network requirements**: Consumer cluster must have direct network access to provider cluster. -- **Wide permissions needed in consumer cluster**: Because the API connector doesn't know up front the names of the APIs it needs to reconcile, it currently runs with full "root" privileges in the consumer cluster. - -- **Connector polling**: API Connector checks for drift between the consumer and provider cluster - periodically through polling. The poll interval can be changed with the `pollInterval` Helm value. - - -## Advanced configuration - -### Multiple connections - -You can connect to multiple provider clusters simultaneously by creating multiple `ClusterConnection` resources with different names and configurations. - -[contact]: https://www.upbound.io/contact-us diff --git a/self-hosted-spaces_versioned_docs/version-1.16/howtos/mcp-connector-guide.md b/self-hosted-spaces_versioned_docs/version-1.16/howtos/mcp-connector-guide.md index f7b3906c..10f1e9b4 100644 --- a/self-hosted-spaces_versioned_docs/version-1.16/howtos/mcp-connector-guide.md +++ b/self-hosted-spaces_versioned_docs/version-1.16/howtos/mcp-connector-guide.md @@ -161,4 +161,3 @@ In this tutorial, you: [control-plane-connector]: /self-hosted-spaces/howtos/ctp-connector [platform-reference-configuration]: https://marketplace.upbound.io/configurations/upbound/platform-ref-aws -[api-connector]: /self-hosted-spaces/howtos/api-connector diff --git a/self-hosted-spaces_versioned_sidebars/version-1.13-sidebars.json b/self-hosted-spaces_versioned_sidebars/version-1.13-sidebars.json index 409bbba1..58359d55 100644 --- a/self-hosted-spaces_versioned_sidebars/version-1.13-sidebars.json +++ b/self-hosted-spaces_versioned_sidebars/version-1.13-sidebars.json @@ -54,7 +54,6 @@ "type": "category", "label": "Connect", "items": [ - "howtos/api-connector", "howtos/ctp-connector", "howtos/mcp-connector-guide", "howtos/query-api" diff --git a/self-hosted-spaces_versioned_sidebars/version-1.14-sidebars.json b/self-hosted-spaces_versioned_sidebars/version-1.14-sidebars.json index 409bbba1..58359d55 100644 --- a/self-hosted-spaces_versioned_sidebars/version-1.14-sidebars.json +++ b/self-hosted-spaces_versioned_sidebars/version-1.14-sidebars.json @@ -54,7 +54,6 @@ "type": "category", "label": "Connect", "items": [ - "howtos/api-connector", "howtos/ctp-connector", "howtos/mcp-connector-guide", "howtos/query-api" diff --git a/self-hosted-spaces_versioned_sidebars/version-1.15-sidebars.json b/self-hosted-spaces_versioned_sidebars/version-1.15-sidebars.json index 808eb867..404bcca6 100644 --- a/self-hosted-spaces_versioned_sidebars/version-1.15-sidebars.json +++ b/self-hosted-spaces_versioned_sidebars/version-1.15-sidebars.json @@ -54,7 +54,6 @@ "type": "category", "label": "Connect", "items": [ - "howtos/api-connector", "howtos/ctp-connector", "howtos/mcp-connector-guide", "howtos/query-api" diff --git a/self-hosted-spaces_versioned_sidebars/version-1.16-sidebars.json b/self-hosted-spaces_versioned_sidebars/version-1.16-sidebars.json index 9cfc6973..527c32a2 100644 --- a/self-hosted-spaces_versioned_sidebars/version-1.16-sidebars.json +++ b/self-hosted-spaces_versioned_sidebars/version-1.16-sidebars.json @@ -57,7 +57,6 @@ "type": "category", "label": "Connect", "items": [ - "howtos/api-connector", "howtos/ctp-connector", "howtos/mcp-connector-guide", "howtos/query-api" diff --git a/src/sidebars/cloud-spaces.js b/src/sidebars/cloud-spaces.js index b235d44f..5348c1b0 100644 --- a/src/sidebars/cloud-spaces.js +++ b/src/sidebars/cloud-spaces.js @@ -35,7 +35,6 @@ module.exports = { type: 'category', label: 'Connect', items: [ - 'howtos/api-connector', 'howtos/ctp-connector', 'howtos/mcp-connector-guide', 'howtos/query-api', diff --git a/src/sidebars/self-hosted-spaces.js b/src/sidebars/self-hosted-spaces.js index b8d0e2c7..4cfb32f7 100644 --- a/src/sidebars/self-hosted-spaces.js +++ b/src/sidebars/self-hosted-spaces.js @@ -57,7 +57,6 @@ module.exports = { type: 'category', label: 'Connect', items: [ - 'howtos/api-connector', 'howtos/ctp-connector', 'howtos/mcp-connector-guide', 'howtos/query-api', diff --git a/static/cli/up_controlplane_api-connector.md b/static/cli/up_controlplane_api-connector.md deleted file mode 100644 index 4e02b390..00000000 --- a/static/cli/up_controlplane_api-connector.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -mdx: - format: md ---- - -Connect an App Cluster to a control plane using API Connector. - - - -#### Usage - -`up controlplane api-connector [flags]` diff --git a/static/cli/up_controlplane_api-connector_install.md b/static/cli/up_controlplane_api-connector_install.md deleted file mode 100644 index bb62ea32..00000000 --- a/static/cli/up_controlplane_api-connector_install.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -mdx: - format: md ---- - -Install api-connector into an consumer cluster. - -The `install` command installs the API Connector into a consumer cluster. - -Note that the API Connector is a preview feature, under active development and -subject to breaking changes. Production use is not recommended. - -#### Examples - -Install the API Connector into the consumer cluster and connect it to the -control plane referred to by the current context: - -```shell -up controlplane api-connector install --consumer-kubeconfig /path/to/kubeconfig -``` - -Install the API Connector into the cluster and connect it to the control plane -referred to by the current context using the provided robot name for -authentication: - -```shell -up controlplane api-connector install --consumer-kubeconfig /path/to/kubeconfig \ - --robot-name upbound-robot-name -``` - -Install the API Connector into the cluster but do not provision a -`ClusterConnection` resource or create a robot for authentication: - -```shell -up controlplane api-connector install --consumer-kubeconfig /path/to/kubeconfig \ - --skip-connection -``` - - -#### Usage - -`up controlplane api-connector install [flags]` -#### Flags - -| Flag | Short Form | Description | -| ---- | ---------- | ----------- | -| `--set` | | Set parameters. | -| `--file` | `-f` | Parameters file. | -| `--bundle` | | Local bundle path. | -| `--upgrade` | | Upgrade or downgrade the API Connector to --version, even if it is already installed. | -| `--version` | | Version of the API Connector to install. If not provided, the latest, known to CLI, will be installed. | -| `--name` | | Name of the related objects for named connection. If not provided, control plane name will be used with api-connector prefix. | -| `--upbound-token` | | API token used to authenticate to the provider control plane. Mutually exclusive with --robot-name. | -| `--skip-connection` | | Skip secret and connection initialization to the control plane. If provided, the connector will be installed without connecting to the control plane. | -| `--consumer-kubeconfig` | | Path to the kubeconfig file for the consumer cluster. If not provided, the default kubeconfig resolution will be used. | -| `--consumer-context` | | Context to use in the kubeconfig file. If not provided, the current context will be used. | -| `--helm-directory` | | Directory to store the Helm chart. If not provided, the default will be used. | diff --git a/static/cli/up_controlplane_api-connector_uninstall.md b/static/cli/up_controlplane_api-connector_uninstall.md deleted file mode 100644 index 886ce587..00000000 --- a/static/cli/up_controlplane_api-connector_uninstall.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -mdx: - format: md ---- - -Uninstall api-connector from an consumer cluster. - -The `uninstall` command uninstalls the API Connector from a cluster. - -#### Examples - -Uninstall the API Connector from the cluster but leave the connections and -secrets in place: - -```shell -up controlplane api-connector uninstall --target-kubeconfig kubeconfig-path-for-deployment-cluster -``` - -Uninstall the API Connector from the cluster and delete the connections and -secrets. API objects created by the API Connector initial installation will not -be deleted: - -```shell -up controlplane api-connector uninstall --all --target-kubeconfig kubeconfig-path-for-deployment-cluster -``` - - -#### Usage - -`up controlplane api-connector uninstall --consumer-kubeconfig=STRING [flags]` -#### Flags - -| Flag | Short Form | Description | -| ---- | ---------- | ----------- | -| `--consumer-kubeconfig` | | **Required** Path to the kubeconfig file for the consumer cluster. If not provided, the default kubeconfig resolution will be used. | -| `--consumer-context` | | Context to use in the kubeconfig file. If not provided, the current context will be used. | -| `--all` | | Uninstall all resources including the connectors and secrets. If not provided, only the connector will be uninstalled. | diff --git a/static/img/api-connector.png b/static/img/api-connector.png deleted file mode 100644 index d16d958e..00000000 Binary files a/static/img/api-connector.png and /dev/null differ diff --git a/static/llms.txt b/static/llms.txt index d93ea332..501526be 100644 --- a/static/llms.txt +++ b/static/llms.txt @@ -78,7 +78,6 @@ Cloud Spaces is Upbound's hosted control plane service. Upbound manages the Spac - [Managed Upbound control planes](https://docs.upbound.io/cloud-spaces/howtos/managed-service): Use Upbound-managed control planes without operating your own Spaces infrastructure. - [Automation and GitOps](https://docs.upbound.io/cloud-spaces/howtos/automation-and-gitops/overview): Manage control plane configuration through GitOps workflows. - [GitOps with Upbound control planes](https://docs.upbound.io/cloud-spaces/howtos/gitops-on-upbound): Connect ArgoCD or Flux to control planes running in Cloud Spaces. -- [API Connector](https://docs.upbound.io/cloud-spaces/howtos/api-connector): Connect external APIs and services to control planes in Cloud Spaces. - [Control Plane Connector](https://docs.upbound.io/cloud-spaces/howtos/ctp-connector): Consume control plane APIs from an app cluster using the control plane connector. - [MCP Connector](https://docs.upbound.io/cloud-spaces/howtos/mcp-connector-guide): Connect managed control planes to your hub cluster. - [Private Network Agent](https://docs.upbound.io/cloud-spaces/howtos/private-network-agent): Route control plane traffic through a private network agent for air-gapped or restricted environments. @@ -116,7 +115,6 @@ Self-Hosted Spaces runs the Spaces platform in your own Kubernetes cluster. You - [Automation and GitOps](https://docs.upbound.io/self-hosted-spaces/howtos/automation-and-gitops/overview): Automate control plane management through GitOps in Self-Hosted Spaces. - [GitOps with ArgoCD](https://docs.upbound.io/self-hosted-spaces/howtos/gitops): Manage Self-Hosted Spaces control planes using ArgoCD. - [Use ArgoCD plugin](https://docs.upbound.io/self-hosted-spaces/howtos/use-argo): Use the Upbound ArgoCD plugin for enhanced GitOps integration. -- [API Connector](https://docs.upbound.io/self-hosted-spaces/howtos/api-connector): Connect external APIs to control planes in Self-Hosted Spaces. - [Control Plane Connector](https://docs.upbound.io/self-hosted-spaces/howtos/ctp-connector): Consume control plane APIs from app clusters in Self-Hosted Spaces. - [MCP Connector](https://docs.upbound.io/self-hosted-spaces/howtos/mcp-connector-guide): Connect managed control planes to the hub cluster in Self-Hosted Spaces. - [Secrets management](https://docs.upbound.io/self-hosted-spaces/howtos/secrets-management): Manage secrets for control planes and Spaces components. diff --git a/vercel.json b/vercel.json index d7b41bca..0855da0a 100644 --- a/vercel.json +++ b/vercel.json @@ -1177,7 +1177,12 @@ }, { "source": "/operate/api-connector(/)?", - "destination": "/self-hosted-spaces/howtos/api-connector", + "destination": "/self-hosted-spaces/howtos/ctp-connector", + "permanent": true + }, + { + "source": "/self-hosted-spaces/howtos/api-connector(/)?", + "destination": "/self-hosted-spaces/howtos/ctp-connector", "permanent": true }, {