diff --git a/README.md b/README.md index 4f731049..7b09bad2 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ Manages the lifecycle of a NATS JetStream deployment. NATS Manager is a standard Kubernetes operator that observes the state of NATS JetStream deployment and reconciles its state according to the desired state. -### How it works +### How It Works This project aims to follow the [Kubernetes Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/). @@ -16,7 +16,7 @@ It uses [Controllers](https://kubernetes.io/docs/concepts/architecture/controlle This project is scaffolded using [Kubebuilder](https://book.kubebuilder.io), and all the Kubebuilder [`makefile` helpers](https://book.kubebuilder.io/reference/makefile-helpers.html) can be used. -## Install +## Installation 1. To install the latest version of the NATS manager on your cluster, run: @@ -118,7 +118,7 @@ You’ll need a Kubernetes cluster to run against. You can use [k3d](https://k3d > **NOTE:** Your NATS Manager automatically uses the current context in your kubeconfig file, that is, whatever cluster `kubectl cluster-info` shows. -### Deploy on the cluster +### Deploy on the Cluster 1. Download Go packages: @@ -166,7 +166,7 @@ To delete the CRDs from the cluster: make uninstall ``` -### Deploy NATS Manager module with [Kyma Lifecycle Manager](https://github.com/kyma-project/lifecycle-manager/tree/main) +### Deploy NATS Manager Module With [Kyma Lifecycle Manager](https://github.com/kyma-project/lifecycle-manager/tree/main) 1. Deploy the Lifecycle Manager to the Kubernetes cluster: @@ -202,7 +202,7 @@ make uninstall kubectl get -n kyma-system kyma ``` -### Uninstall NATS Manager module with [Kyma Lifecycle Manager](https://github.com/kyma-project/lifecycle-manager/tree/main) +### Uninstall NATS Manager Module With [Kyma Lifecycle Manager](https://github.com/kyma-project/lifecycle-manager/tree/main) 1. Delete NATS Custom Resource (CR) from the Kubernetes cluster (if exists): @@ -237,7 +237,7 @@ make uninstall kubectl get -n kyma-system kyma ``` -## E2E tests +## E2E Tests > **NOTE:** Because the E2E tests need a Kubernetes cluster to run on, they are separated from the remaining tests and are only executed if the `e2e` build tags are passed. diff --git a/docs/contributor/development.md b/docs/contributor/development.md index cf79e5a2..c7391691 100644 --- a/docs/contributor/development.md +++ b/docs/contributor/development.md @@ -14,12 +14,10 @@ Projects created by Kubebuilder contain a Makefile with tooling that must be loc - [golangci-lint](https://golangci-lint.run/) ## Available Commands + Commands are available for easier development and installation of the NATS Manager. To find out which commands are available and for some more details about each command, run: ```bash make help ``` - - - diff --git a/docs/contributor/governance.md b/docs/contributor/governance.md index 46913036..67e4050c 100644 --- a/docs/contributor/governance.md +++ b/docs/contributor/governance.md @@ -3,7 +3,7 @@ Some quality aspects are covered by automated verification, so you must locally execute tooling before a commit. This document guides you through the development flow. -## Modifying the API definitions +## Modifying the API Definitions This project uses the [controller-gen](https://book.kubebuilder.io/reference/controller-gen.html) tool provided by [Kubebuilder](https://book.kubebuilder.io/). To modify the API definitions, you must adapt the ["marker comments"](https://book.kubebuilder.io/reference/markers.html) in the Go code. @@ -13,15 +13,17 @@ The rules are written using the [Common Expression Language](https://github.com/ For further information and examples, look to the [Kubernetes documentation](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#validation) of validation rules and the CEL [language definition](https://github.com/google/cel-spec/blob/v0.10.0/doc/langdef.md). After the modifications, run the following command to generate the new manifests such as CRs and CRDs: - ```sh - make manifests - ``` + +```sh +make manifests +``` If changes to the `runtime.Object` interface were made, the `DeepCopy` functions must be updated as well. The generation is controlled by [Kubebuilder markers](https://book.kubebuilder.io/reference/markers/object.html?highlight=deep#objectdeepcopy). - ```sh - make generate - ``` + +```sh +make generate +``` ## Sourcecode Linting diff --git a/docs/contributor/installation.md b/docs/contributor/installation.md index 28467b33..d8ba51fb 100644 --- a/docs/contributor/installation.md +++ b/docs/contributor/installation.md @@ -2,9 +2,9 @@ There are several ways to install the NATS Manager. For development, you must run some make targets beforehand. -For information about the prerequisites, refer to [Development](./development.md) and for a detailed guide to the development flow, visit [Governance](./governance.md). +For information about the prerequisites, refer to [Development](./development.md), and for a detailed guide to the development flow, visit [Governance](./governance.md). -## Run the manager on a (k3d) cluster using a Docker image +## Run the NATS Manager on a (k3d) Cluster Using a Docker Image ### Installation @@ -80,7 +80,7 @@ For information about the prerequisites, refer to [Development](./development.md make uninstall ``` -## Run the manager on a cluster using the Go runtime environment +## Run the NATS Manager on a Cluster Using the Go Runtime Environment ### Installation @@ -114,7 +114,7 @@ Remove the resources. make uninstall ``` -## Run the NATS Manager using Kyma's Lifecycle Manager +## Run the NATS Manager Using Kyma’s Lifecycle Manager [Kyma's Lifecycle Manager](https://github.com/kyma-project/lifecycle-manager) helps manage the lifecycle of each module in the cluster and can be used to install the NATS Manager. diff --git a/docs/contributor/testing.md b/docs/contributor/testing.md index fe545c8b..b1aea679 100644 --- a/docs/contributor/testing.md +++ b/docs/contributor/testing.md @@ -87,7 +87,6 @@ The E2E test consists of four consecutive steps. If desired, you can run them in make e2e-cleanup ``` - ## CI/CD This project uses [Prow](https://docs.prow.k8s.io/docs/) and [GitHub Actions](https://docs.github.com/en/actions) as part of the development cycle. diff --git a/docs/contributor/troubleshooting.md b/docs/contributor/troubleshooting.md index 6218f36d..00f6ebaa 100644 --- a/docs/contributor/troubleshooting.md +++ b/docs/contributor/troubleshooting.md @@ -2,26 +2,24 @@ This document contains tips and tricks to common problems with the NATS Manager and will be updated continuously. -## Troubleshooting: Installing NATS Manager using a Docker image +## Troubleshooting: Installing NATS Manager Using a Docker Image -### Error while deploying the NATS Manager +### Error While Deploying the NATS Manager **Symptom:** The `make deploy` step fails with the following error message: `Error from server (NotFound): error when creating "STDIN": namespaces kyma-system not found` -**Cause:** The Namespace of the Deployment does not exist yet. +**Cause:** The namespace of the Deployment does not exist yet. -**Remedy:** Create the Namespace. +**Remedy:** Create the namespace. ```sh kubectl create ns kyma-system ``` -## Reach out to us +## Reach Out to Us -If you encounter an issue or want to report a bug, please create a [GitHub issue](https://github.com/kyma-project/nats-manager/issues) with background information and -steps how to reproduce. +If you encounter an issue or want to report a bug, please create a [GitHub issue](https://github.com/kyma-project/nats-manager/issues) with background information and steps how to reproduce. -If you want to contact the eventing team directly, you can reach us via Slack [Eventing channel](https://kyma-community.slack.com/archives/CD1C9GZMK) -or tag us `@kyma-eventing` in the Slack [Kyma Tech channel](https://sap-ti.slack.com/archives/C0140PCSJ5Q) +If you want to contact the eventing team directly, you can reach us via Slack [Eventing channel](https://kyma-community.slack.com/archives/CD1C9GZMK), or tag us `@kyma-eventing` in the Slack [Kyma Tech channel](https://sap-ti.slack.com/archives/C0140PCSJ5Q). diff --git a/docs/user/01-manager.md b/docs/user/01-manager.md index e7a8714c..6a5e6745 100644 --- a/docs/user/01-manager.md +++ b/docs/user/01-manager.md @@ -1,36 +1,35 @@ # NATS Manager -This module ships the NATS Manager. +The Kyma NATS module ships the NATS Manager. ## Module Lifecycle ### Starting NATS Manager -Upon starting the NATS Manager, the controller (following the [Kubebuilder concept](https://book.kubebuilder.io/architecture.html)) creates, watches and reconciles the following resources: +Upon starting the NATS Manager, the controller (following the [Kubebuilder concept](https://book.kubebuilder.io/architecture.html)) creates, watches, and reconciles the following resources: - - ConfigMap (cm) - - Secret (sc) - - Service (sv) - - Stateful Set (sts) - - DestinationRule (dr, [Istio](https://istio.io)) +- ConfigMap (cm) +- Secret (sc) +- Service (sv) +- Stateful Set (sts) +- DestinationRule (dr, [Istio](https://istio.io)) ![Start NATS manager](./assets/Start_nats_manager.drawio.svg) -### Reacting to NATS CR changes +### Reacting to NATS CR Changes The NATS Manager reacts to changes of the NATS CR to adapt the resources mentioned above to the desired state. For details how to configure NATS using the CR, visit the [Configuration documentation](./02-configuration.md). ![Reacting to NATS CR changes](./assets/reacting_to_nats_cr_changes.drawio.svg) -### Reacting to resource changes +### Reacting to Resource Changes When resources are changed or deleted, the controller reacts by restoring the defaults according to the NATS CR. Thus, if you want to change the resources, you must edit the NATS CR; you cannot change the resources directly. ![Reacting to resource changes](assets/reacting_to_resource_changes.drawio.svg) - -### Overview: NATS Manager watches resources +### Overview: NATS Manager Watches Resources ![NM watches resources](assets/NC_watches_resources.drawio.svg) diff --git a/docs/user/10-nats-server-system-events.md b/docs/user/10-nats-server-system-events.md index a23fab43..98822dab 100644 --- a/docs/user/10-nats-server-system-events.md +++ b/docs/user/10-nats-server-system-events.md @@ -1,26 +1,33 @@ -# Acquiring NATS server system account credentials +# Acquiring NATS Server System Account Credentials ## Context -Accessing certain resources in NATS requires [`system_account` privileges](https://docs.nats.io/running-a-nats-service/configuration/sys_accounts). Kyma automatically generates a `system account` user using a Secret dubbed `eventing-nats-secret` in the `kyma-system` Namespace. +Accessing certain resources in NATS requires [`system_account` privileges](https://docs.nats.io/running-a-nats-service/configuration/sys_accounts). Kyma automatically generates a `system account` user using a Secret dubbed `eventing-nats-secret` in the `kyma-system` namespace. ## Procedure -To acquire the credentials, run the following command: +To get the credentials, run: ```bash kubectl get secrets -n kyma-system eventing-nats-secret -ogo-template='{{index .data "resolver.conf"|base64decode}}'| grep 'user:' | tr -d '{}' ``` -### Result: +### Result + You get the credentials for the `system account` user in the following format: + ```bash user: admin, password: ``` -### Next steps: + +### Next Steps + 1. To access the NATS server with the [nats-cli tool](https://github.com/nats-io/natscli), forward its port: + ```bash kubectl port-forward -n kyma-system svc/eventing-nats 4222 + 2. To send your NATS commands, pass the credentials: + ```bash nats server info --user admin --password diff --git a/docs/user/README.md b/docs/user/README.md index a78436fc..53ae91d7 100644 --- a/docs/user/README.md +++ b/docs/user/README.md @@ -1,4 +1,4 @@ -# NATS module +# NATS Module This module ships the NATS Manager, which is responsible for managing the lifecycle of a [NATS JetStream](https://docs.nats.io/nats-concepts/jetstream) deployment. It observes the state of the NATS cluster and reconciles its state according to the desired state. @@ -10,13 +10,13 @@ Kyma Eventing can use NATS as a backend to process events and send them to subsc ## Documentation Overview - - [General information about the NATS Manager](./01-manager.md) - - [Details how to configure the NATS module](./02-configuration.md) +- [General information about the NATS Manager](./01-manager.md) +- [Details how to configure the NATS module](./02-configuration.md) There is further documentation including more technical details aimed at possible contributors: - - [General information about the setup](../contributor/development.md) - - [Guide to the project governance](../contributor/governance.md) - - [Installation guide](../contributor/installation.md) - - [Information about the test coverage](../contributor/testing.md) - - [Troubleshooting](../contributor/troubleshooting.md) +- [General information about the setup](../contributor/development.md) +- [Guide to the project governance](../contributor/governance.md) +- [Installation guide](../contributor/installation.md) +- [Information about the test coverage](../contributor/testing.md) +- [Troubleshooting](../contributor/troubleshooting.md) diff --git a/docs/user/_sidebar.md b/docs/user/_sidebar.md index 1f77eccf..58720175 100644 --- a/docs/user/_sidebar.md +++ b/docs/user/_sidebar.md @@ -1,5 +1,5 @@ -- [Home](/) -- [NATS Manager](README.md) -- [Module Lifecycle](01-manager.md) -- [Module Configuration](02-configuration.md) -- [Acquiring NATS server system account credentials](10-nats-server-system-events.md) \ No newline at end of file +- [Back to Kyma Home](/) +- [NATS Manager](/nats-manager/user/README.md) +- [Module Lifecycle](/nats-manager/user/01-manager.md) +- [Module Configuration](/nats-manager/user/02-configuration.md) +- [Acquiring NATS Server System Account Credentials](/nats-manager/user/10-nats-server-system-events.md) \ No newline at end of file