Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
25 changes: 24 additions & 1 deletion config/samples/provider-widget-crd.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -42,4 +42,27 @@ spec:
jsonPath: .spec.size
- name: Phase
type: string
jsonPath: .status.phase
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"
23 changes: 0 additions & 23 deletions config/samples/widget.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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"
26 changes: 21 additions & 5 deletions docs/content/setup/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
```

Expand All @@ -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
```
Expand All @@ -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).
Expand Down
91 changes: 91 additions & 0 deletions docs/content/usage/gitops.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion docs/content/usage/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
Loading