Improve README. Modernize examples.

Author: samuelattwood

README.md

@@ -9,22 +9,32 @@
 
 ## JetStream Controller
 
-The JetStream controllers allows you to manage [NATS JetStream](https://github.com/nats-io/jetstream) [Streams](https://github.com/nats-io/jetstream#streams-1) and [Consumers](https://github.com/nats-io/jetstream#consumers-1) via K8S CRDs.
+The JetStream controllers allows you to manage [NATS JetStream](https://github.com/nats-io/jetstream) [Streams](https://docs.nats.io/nats-concepts/jetstream/streams), [Consumers](https://docs.nats.io/nats-concepts/jetstream/consumers), [Key/Value Stores](https://docs.nats.io/nats-concepts/jetstream/key-value-store), and [Object Stores](https://docs.nats.io/nats-concepts/jetstream/obj_store) via Kubernetes CRDs.
+
+Resources managed by NACK controllers are expected to _exclusively_ be managed by NACK, and configuration state will be enforced if mutated by an external client.
+
+## [API Reference](docs/api.md)
 
 ### Getting started
 
-First install the JetStream CRDs:
+Install with Helm:
 
-```sh
-$ kubectl apply -f https://github.com/nats-io/nack/releases/latest/download/crds.yml
 ```
+helm repo add nats https://nats-io.github.io/k8s/helm/charts/
+helm upgrade --install nats nats/nats --set config.jetstream.enabled=true
+helm upgrade --install nack nats/nack --set jetstream.nats.url=nats://nats.default.svc.cluster.local:4222
+```
+
+#### (Optional) Enable Experimental `controller-runtime` Controllers
 
-Now install with Helm:
+> **Note**: If migrating an existing install to the `controller-runtime` architecture, it is advisable to first enable with the `-read-only` flag.
+>
+> The `jetstream-controller` logs will preview any changes that would be made to existing resources.
+>
+> The updated architecture will more reliably enforce state. If all resources are in-sync with NACK, no changes are expected.
 
 ```
-helm repo add nats https://nats-io.github.io/k8s/helm/charts/
-helm install nats nats/nats --set=config.jetstream.enabled=true
-helm install nack nats/nack --set jetstream.nats.url=nats://nats:4222
+helm upgrade -n nack nack nats/nack --set jetstream.additionalArgs={-control-loop=true}
 ```
 
 #### Creating Streams and Consumers
@@ -66,6 +76,28 @@ spec:
   filterSubject: orders.received
   maxDeliver: 20
   ackPolicy: explicit
+---
+apiVersion: jetstream.nats.io/v1beta2
+kind: KeyValue
+metadata:
+  name: my-key-value
+spec:
+  bucket: my-key-value
+  history: 20
+  storage: file
+  maxBytes: 2048
+  compression: true
+---
+apiVersion: jetstream.nats.io/v1beta2
+kind: ObjectStore
+metadata:
+  name: my-object-store
+spec:
+  bucket: my-object-store
+  storage: file
+  replicas: 1
+  maxBytes: 536870912 # 512 MB
+  compression: true
 ```
 
 ```sh
@@ -178,7 +210,7 @@ metadata:
 spec:
   name: a
   servers:
-  - nats://nats:4222
+    - nats://nats:4222
   tls:
     secret:
       name: nack-a-tls
@@ -209,31 +241,32 @@ Server URL and TLS certificates.
 
 ```sh
 # Install cert-manager
-kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.6.0/cert-manager.yaml
+kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.17.0/cert-manager.yaml
 
 # Install TLS certs
 cd examples/secure
+
 # Install certificate issuer
 kubectl apply -f issuer.yaml
+
 # Install account A cert
 kubectl apply -f nack-a-client-tls.yaml
+
 # Install server cert
 kubectl apply -f server-tls.yaml
+
 # Install nats-box cert
 kubectl apply -f client-tls.yaml
 
 # Install NATS cluster
-helm install -f nats-helm.yaml nats nats/nats
+helm upgrade --install -f nats-helm.yaml nats nats/nats
+
 # Verify pods are healthy
 kubectl get pods
 
-# Install nats-box to run nats cli later
-kubectl apply -f nats-client-box.yaml
-
 # Install JetStream Controller from nack
-helm install --set jetstream.enabled=true jetstream-controller nats/nack
-# Install CRDs
-kubectl apply -f ../../deploy/crds.yml
+helm upgrade --install nack nats/nack --set jetstream.enabled=true
+
 # Verify pods are healthy
 kubectl get pods
 
@@ -242,6 +275,7 @@ kubectl apply -f nack/nats-account-a.yaml
 
 # Create stream using account A
 kubectl apply -f nack/nats-stream-foo-a.yaml
+
 # Create consumer using account A
 kubectl apply -f nack/nats-consumer-bar-a.yaml
 ```
@@ -251,30 +285,28 @@ container to run the management CLI.
 
 ```sh
 # Get container shell
-kubectl exec -it nats-client-box-abc-123 -- sh
-# Change to TLS directory
-cd /etc/nats-certs/clients/nack-a-tls
+kubectl exec -it deployment/nats-box -- /bin/sh
 ```
 
 There should now be some Streams available, verify with `nats` command.
 
 ```sh
 # List streams
-nats --tlscert tls.crt --tlskey tls.key --tlsca ca.crt -s tls://nats.default.svc.cluster.local stream ls
+nats stream ls
 ```
 
 You can now publish messages on a Stream.
 
 ```sh
 # Push message
-nats --tlscert tls.crt --tlskey tls.key --tlsca ca.crt -s tls://nats.default.svc.cluster.local pub foo hi
+nats pub foo hi
 ```
 
 And pull messages from a Consumer.
 
 ```sh
 # Pull message
-nats --tlscert tls.crt --tlskey tls.key --tlsca ca.crt -s tls://nats.default.svc.cluster.local consumer next foo bar
+nats consumer next foo bar
 ```
 
 ### Local Development
@@ -298,6 +330,7 @@ nats-server -DV -js
 ```
 
 Build Docker image
+
 ```sh
 make jetstream-controller-docker ver=1.2.3
 ```
@@ -314,15 +347,15 @@ For more information see the
 
 ```
 helm repo add nats https://nats-io.github.io/k8s/helm/charts/
-helm install my-nats nats/nats
+helm upgrade --install nats nats/nats
 ```
 
 ### Configuring
 
 ```yaml
 reloader:
   enabled: true
-  image: natsio/nats-server-config-reloader:0.6.0
+  image: natsio/nats-server-config-reloader:0.16.1
   pullPolicy: IfNotPresent
 ```
 
@@ -337,6 +370,7 @@ make nats-server-config-reloader
 ```
 
 Build Docker image
+
 ```sh
 make nats-server-config-reloader-docker ver=1.2.3
 ```
@@ -350,14 +384,14 @@ For more information see the
 
 ```
 helm repo add nats https://nats-io.github.io/k8s/helm/charts/
-helm install my-nats nats/nats
+helm upgrade --install --create-namespace --namespace nats nats nats/nats
 ```
 
 ### Configuring
 
 ```yaml
 bootconfig:
-  image: natsio/nats-boot-config:0.5.2
+  image: natsio/nats-boot-config:0.16.1
   pullPolicy: IfNotPresent
 ```
 
@@ -372,6 +406,9 @@ make nats-boot-config
 ```
 
 Build Docker image
+
 ```sh
 make nats-boot-config-docker ver=1.2.3
 ```
+
+## API Reference

cicd/Dockerfile

@@ -1,7 +1,7 @@
-#syntax=docker/dockerfile-upstream:1.13
+#syntax=docker/dockerfile:1.13
 ARG GO_APP
 
-FROM alpine:3.21.2 as deps
+FROM alpine:3.21.3 as deps
 
 ARG GO_APP
 ARG GORELEASER_DIST_DIR=/go/src/dist
@@ -28,7 +28,7 @@ RUN <<EOT
   cp ${BIN_PATH} /go/bin
 EOT
 
-FROM alpine:3.21.2
+FROM alpine:3.21.3
 
 ARG GO_APP
 ENV GO_APP ${GO_APP}

cicd/Dockerfile_goreleaser

@@ -1,4 +1,4 @@
-#syntax=docker/dockerfile-upstream:1.5
+#syntax=docker/dockerfile:1.13
 FROM --platform=$BUILDPLATFORM golang:1.24.0-bullseye as build