diff --git a/config/samples/provider-widget-crd.yaml b/config/samples/provider-widget-crd.yaml index bfa70450a..a0d65d07d 100644 --- a/config/samples/provider-widget-crd.yaml +++ b/config/samples/provider-widget-crd.yaml @@ -42,4 +42,27 @@ spec: jsonPath: .spec.size - name: Phase type: string - jsonPath: .status.phase \ No newline at end of file + jsonPath: .status.phase +--- +# Related resources: connection details and tuning the service hands to every +# consumer. Anything matching the binding's selector syncs to the consumer. +apiVersion: v1 +kind: Secret +metadata: + name: widgets-connection + namespace: default + labels: + widgets.example.org/related: "true" +stringData: + endpoint: https://widgets.internal.example.org + api-key: demo-not-a-real-key +--- +apiVersion: v1 +kind: ConfigMap +metadata: + name: widgets-tuning + namespace: default + labels: + widgets.example.org/related: "true" +data: + pointiness: "11" diff --git a/config/samples/widget.yaml b/config/samples/widget.yaml index e8a86eeab..c4c05b74f 100644 --- a/config/samples/widget.yaml +++ b/config/samples/widget.yaml @@ -17,26 +17,3 @@ metadata: namespace: default spec: size: large ---- -# Related resources: connection details and tuning the service hands to every -# consumer. Anything matching the binding's selector syncs to the consumer. -apiVersion: v1 -kind: Secret -metadata: - name: widgets-connection - namespace: default - labels: - widgets.example.org/related: "true" -stringData: - endpoint: https://widgets.internal.example.org - api-key: demo-not-a-real-key ---- -apiVersion: v1 -kind: ConfigMap -metadata: - name: widgets-tuning - namespace: default - labels: - widgets.example.org/related: "true" -data: - pointiness: "11" diff --git a/docs/content/setup/quickstart.md b/docs/content/setup/quickstart.md index 88bcd0174..8cdde0eea 100644 --- a/docs/content/setup/quickstart.md +++ b/docs/content/setup/quickstart.md @@ -8,7 +8,10 @@ description: > ## Prerequisites - [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) -- [kubectl bind plugin](kubectl-plugin.md) installed +- For the backend walkthrough: [kubectl bind plugin](kubectl-plugin.md) installed + +To try synchronization without a backend or login, follow the +[core-only GitOps example](../usage/gitops.md#try-the-core-without-a-backend). ## Start with kbind @@ -30,7 +33,7 @@ After the development environment is ready, you can: ```bash kubectl bind catalog - kubectl bind export widgets --kubeconfig=.kbind-quickstart/consumer.kubeconfig \ + kubectl bind export widgets --kubeconfig=consumer.kubeconfig \ --install-konnector=false ``` @@ -39,7 +42,7 @@ After the development environment is ready, you can: 3. **Verify bound resources:** ```bash - export KUBECONFIG="$PWD/.kbind-quickstart/consumer.kubeconfig" + export KUBECONFIG="$PWD/consumer.kubeconfig" kubectl get connections,clusterbindings kubectl wait --for=condition=Established crd/widgets.example.org --timeout=120s ``` @@ -61,9 +64,22 @@ After the development environment is ready, you can: 5. **Check the resource synced to the provider:** ```bash - kubectl --kubeconfig=.kbind-quickstart/provider.kubeconfig -n default \ + kubectl --kubeconfig=provider.kubeconfig -n default \ wait --for=create widget/my-widget --timeout=120s - kubectl --kubeconfig=.kbind-quickstart/provider.kubeconfig -n default get widgets + kubectl --kubeconfig=provider.kubeconfig -n default get widgets + ``` + +6. **Verify status returns to the consumer:** + + The sample has no Widget service controller. Simulate its status update on the + provider, then wait for the consumer to receive it: + + ```bash + kubectl --kubeconfig=provider.kubeconfig -n default \ + patch widget my-widget --subresource=status --type=merge \ + -p '{"status":{"phase":"Running"}}' + kubectl --kubeconfig=consumer.kubeconfig -n default \ + wait --for=jsonpath='{.status.phase}'=Running widget/my-widget --timeout=120s ``` For other service APIs, see the [integration examples](../usage/integrations/index.md). When finished, follow the development guide's [cleanup](../developers/dev-environment/kind.md#cleanup). diff --git a/docs/content/usage/gitops.md b/docs/content/usage/gitops.md index bded92691..c0c504fc1 100644 --- a/docs/content/usage/gitops.md +++ b/docs/content/usage/gitops.md @@ -2,6 +2,97 @@ The v2 core accepts ordinary Kubernetes YAML. You can manage a Connection and its explicit bindings with your existing GitOps controller, no browser onboarding or continuously running CLI is required. +## Try the core without a backend + +This local example uses the existing demo samples to supply credentials, a Connection, +and a ClusterBinding directly. It needs no backend, catalog, login, or `kubectl bind` +plugin. Use a v2 source checkout, Go matching `go.mod`, Docker, kind, and kubectl. +Run commands from the repository root. + +The demo creates or reuses kind clusters named `kbind-provider` and `kbind-consumer`. +Use fresh, disposable clusters with those names: the script applies sample resources +and replaces its credential Secret. It writes administrator kubeconfigs under `/tmp` +and copies the provider kubeconfig into a consumer Secret. These credentials are for +this local demo only; use restricted provider credentials and secure Secret delivery +for a real deployment. + +### Prepare the two clusters + +```sh +make konnector +make demo +``` + +The script installs the exported Widget CRD and related Secret/ConfigMap on the provider. +On the consumer it installs API definitions, creates the credential Secret, and applies +`config/samples/binding.yaml`. That file connects `demo-provider` to the Secret and +selects `widgets.example.org` through ClusterBinding `widgets`. + +In a second terminal at the repository root, start the konnector and leave it running: + +```sh +KUBECONFIG=/tmp/kbind-consumer.kubeconfig ./bin/konnector +``` + +These kubeconfigs use host-mapped endpoints, so this example runs the konnector on your +workstation. They are not suitable for a konnector Pod in another cluster. + +### Verify synchronization + +In the first terminal, wait for readiness before creating a Widget: + +```sh +kubectl --kubeconfig /tmp/kbind-consumer.kubeconfig wait \ + --for=condition=Ready connection/demo-provider clusterbinding/widgets --timeout=120s +kubectl --kubeconfig /tmp/kbind-consumer.kubeconfig wait \ + --for=condition=Established crd/widgets.example.org --timeout=120s +kubectl --kubeconfig /tmp/kbind-consumer.kubeconfig apply -f config/samples/widget.yaml +kubectl --kubeconfig /tmp/kbind-provider.kubeconfig -n default wait \ + --for=create widget/my-widget --timeout=120s +kubectl --kubeconfig /tmp/kbind-provider.kubeconfig -n default wait \ + --for=jsonpath='{.spec.size}'=large widget/my-widget --timeout=120s +``` + +There is no Widget service controller in this demo. Simulate its status update on the +provider and verify that it reaches the consumer: + +```sh +kubectl --kubeconfig /tmp/kbind-provider.kubeconfig -n default patch widget my-widget \ + --subresource=status --type=merge -p '{"status":{"phase":"Running"}}' +kubectl --kubeconfig /tmp/kbind-consumer.kubeconfig -n default wait \ + --for=jsonpath='{.status.phase}'=Running widget/my-widget --timeout=120s +``` + +The binding also copies the provider's related Secret and ConfigMap. Check their +ownership markers without printing Secret data: + +```sh +kubectl --kubeconfig /tmp/kbind-consumer.kubeconfig -n default wait \ + --for=create secret/widgets-connection configmap/widgets-tuning --timeout=120s +kubectl --kubeconfig /tmp/kbind-consumer.kubeconfig -n default get \ + secret/widgets-connection configmap/widgets-tuning \ + -o 'custom-columns=NAME:.metadata.name,BINDING:.metadata.annotations.core\.kbind\.io/related-binding' +kubectl --kubeconfig /tmp/kbind-consumer.kubeconfig get clusterbinding widgets \ + -o jsonpath='{.metadata.uid}{"\n"}' +``` + +Both `BINDING` values should match the ClusterBinding UID. The consumer sample creates +only the Widget; the konnector creates these related copies. + +### Clean up + +Stop the host konnector with Ctrl-C, then remove only the disposable demo clusters and +their credential files: + +```sh +kind delete cluster --name kbind-consumer +kind delete cluster --name kbind-provider +rm /tmp/kbind-consumer.kubeconfig /tmp/kbind-provider.kubeconfig +``` + +For an existing deployment, follow [Pruning is unbinding](#pruning-is-unbinding) instead +of deleting clusters. To manage the same core inputs declaratively, continue below. + ## Separate definitions, credentials, and generated state Manage these layers deliberately: diff --git a/docs/content/usage/troubleshooting.md b/docs/content/usage/troubleshooting.md index f7063b904..2df9f4368 100644 --- a/docs/content/usage/troubleshooting.md +++ b/docs/content/usage/troubleshooting.md @@ -127,7 +127,7 @@ The engine copies only bound instance `spec` up and `status` down, not arbitrary ## Related resources do not appear -Check the declared direction and source namespace. `FromProvider` means create the source on the provider, not on the consumer. The full `config/samples/widget.yaml` contains local Secret/ConfigMap manifests as well as a Widget, applying it on the consumer does not demonstrate provider-to-consumer copying. +Check the declared direction and source namespace. `FromProvider` means create the source on the provider, not on the consumer. The demo defines its source Secret/ConfigMap in `config/samples/provider-widget-crd.yaml`; apply that file on the provider. Apply `config/samples/widget.yaml` only on the consumer. See the [core-only example](gitops.md#try-the-core-without-a-backend) for commands that verify copying and ownership. Check selectors, source/target RBAC, and target ownership. A foreign Secret/ConfigMap is silently left untouched, `Adopt` and binding instance conflict counts do not apply to these collisions. Source labels are not copied to the target.