From b8800ef260796297f4b35ca9b2153ac7b7f74a7a Mon Sep 17 00:00:00 2001 From: Stacey Salamon Date: Wed, 16 Oct 2024 10:24:43 +0200 Subject: [PATCH] docs: update installation instructions --- docs/docs/authentication.md | 49 +++----- docs/docs/index.md | 20 ++-- docs/docs/installation/helm.md | 147 +++++++++--------------- docs/docs/installation/kubectl.md | 18 +-- docs/docs/installation/prerequisites.md | 28 ++--- docs/docs/installation/uninstalling.md | 65 +++++++++-- 6 files changed, 158 insertions(+), 169 deletions(-) diff --git a/docs/docs/authentication.md b/docs/docs/authentication.md index cc20afa7..a088505d 100644 --- a/docs/docs/authentication.md +++ b/docs/docs/authentication.md @@ -1,33 +1,32 @@ --- -title: "Authenticating" -linkTitle: "Authenticating" +title: "Authentication" +linkTitle: "Authentication" weight: 10 --- -To get authenticated and authorized, set up the communication between the Aiven Operator for Kubernetes and Aiven by -using a token stored in a Kubernetes Secret. You can then refer to the `Secret` name on every custom resource in -the `authSecretRef` field. +# Authentication -!!! important - If you don't have an Aiven account yet, sign - up [here](https://console.aiven.io/signup?utm_source=github&utm_medium=organic&utm_campaign=k8s-operator&utm_content=signup) - for a free trial 🦀 +Set up the communication between the Aiven Operator and the Aiven Platform by using a token stored in a Kubernetes Secret. +You can then refer to the Secret's name on every custom resource in the `authSecretRef` field. -1\. Generate an authentication token +## Prerequisites -Refer to [our documentation article](https://aiven.io/docs/platform/concepts/authentication-tokens) to generate your -authentication token. +An Aiven user account. [Sign up for free](https://console.aiven.io/signup?utm_source=github&utm_medium=organic&utm_campaign=k8s-operator&utm_content=signup). -2\. Create the Kubernetes Secret +## Store a token in a Secret -The following command creates a Secret named `aiven-token` with a `token` field containing the authentication token: +1\. [Create a personal token](https://aiven.io/docs/platform/howto/create_authentication_token) in the Aiven Console. + +2\. To create a Kubernetes Secret, run: ```shell kubectl create secret generic aiven-token --from-literal=token="TOKEN" ``` -When managing your Aiven resources, we will be using the created Secret in the `authSecretRef` field. It will look like -the example below: +Where `TOKEN` is your personal token. This creates a Secret named `aiven-token`. + +When managing your Aiven resources, you use the Secret in the `authSecretRef` field. The following is an example +for a PostgreSQL service with the token: ```yaml apiVersion: aiven.io/v1alpha1 @@ -39,20 +38,4 @@ spec: name: aiven-token key: token [ ... ] -``` - -Also, note that within Aiven, all resources are conceptually inside a _Project_. By default, a random project name is -generated when you signup, but you can -also [create new projects](https://aiven.io/docs/platform/howto/manage-project). - -The Project name is required in most of the resources. It will look like the example below: - -```yaml -apiVersion: aiven.io/v1alpha1 -kind: PostgreSQL -metadata: - name: pg-sample -spec: - project: PROJECT_NAME - [ ... ] -``` +``` \ No newline at end of file diff --git a/docs/docs/index.md b/docs/docs/index.md index 481c566f..4f592a93 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -4,16 +4,22 @@ linkTitle: "" url: / --- -# Welcome to Aiven Operator for Kubernetes +# Aiven Operator for Kubernetes® docs -Provision and manage [Aiven services](https://aiven.io) from your Kubernetes cluster. +Provision and manage [Aiven services](https://aiven.io/docs/products/services) from your Kubernetes cluster. -## What is Aiven? +## The Aiven Data and AI Platform -Aiven offers managed services for the best open source data technologies, on a cloud of your choice. +Aiven provides managed open source services for streaming, storing and analyzing data on all major clouds. All services run reliably and securely in the clouds of your choice, are observable, and can easily be integrated with each other and with external 3rd party tools. -We offer multiple cloud options because we believe that everyone should have access to great data platforms wherever they host their applications. Our customers tell us they love it because they know that they aren’t locked in to one particular cloud platform for all their data needs. +The Aiven Platform combines open-choice services to rapidly stream, store and serve data across major cloud providers — simply and securely. Aiven is trusted by thousands of customers worldwide to power their innovation and create next-generation applications confidently and quickly. -## Contributing +## Get started -The [contribution guide](./contributing/index.md) covers everything you need to know about how you can contribute to Aiven Operator for Kubernetes. The [developer guide](./contributing/developer-guide.md) will help you onboard as a developer. +- Follow the [setup guides](./installation/prerequisites.md) to install Aiven Operator and create a token. +- Then try out the [resource examples](./aiven-operator/resources/project.md) to set up a project or deploy a service, or review the [API reference](./api-reference/index.md). +- View the [Aiven documentation](https://aiven.io/docs) for more information on the Aiven Platform and services. + +## Contribute + +The [contribution guide](./contributing/index.md) covers everything you need to know about how you can contribute to Aiven Kubernetes Operator. The [developer guide](./contributing/developer-guide.md) gets you set up with the all the tools you need. diff --git a/docs/docs/installation/helm.md b/docs/docs/installation/helm.md index 699c1a0d..c871d938 100644 --- a/docs/docs/installation/helm.md +++ b/docs/docs/installation/helm.md @@ -4,124 +4,85 @@ linkTitle: "Install with Helm (recommended)" weight: 10 --- -## Installing +# Install with Helm -The Aiven Operator for Kubernetes can be installed via [Helm](https://helm.sh/). +The Aiven Operator for Kubernetes® can be installed with [Helm](https://helm.sh/). Before you start, make sure you have the [prerequisites](prerequisites.md). -Before you start, make sure you have the [prerequisites](prerequisites.md). +1\. Add the [Aiven Helm chart repository](https://github.com/aiven/aiven-charts) and update yoru local Helm information by running: -First add the [Aiven Helm repository](https://github.com/aiven/aiven-charts): + ```shell + helm repo add aiven https://aiven.github.io/aiven-charts && helm repo update + ``` -```shell -helm repo add aiven https://aiven.github.io/aiven-charts && helm repo update -``` +2\. Install Custom Resource Definitions (CRDs) by running: -### Install Custom Resource Definitions + ```shell + helm install aiven-operator-crds aiven/aiven-operator-crds + ``` -```shell -helm install aiven-operator-crds aiven/aiven-operator-crds -``` +3\. To verify the installation, run: -Verify the installation: + ```shell + kubectl api-resources --api-group=aiven.io + ``` -```shell -kubectl api-resources --api-group=aiven.io -``` + The output is similar to the following: -The output is similar to the following: + ```{ .shell .no-copy } + NAME SHORTNAMES APIVERSION NAMESPACED KIND + connectionpools aiven.io/v1alpha1 true ConnectionPool + databases aiven.io/v1alpha1 true Database + ... + ``` -```{ .shell .no-copy } -NAME SHORTNAMES APIVERSION NAMESPACED KIND -connectionpools aiven.io/v1alpha1 true ConnectionPool -databases aiven.io/v1alpha1 true Database -... < several omitted lines > -``` +4\. To install the Aiven Operator, run: -### Install the Operator - -```shell -helm install aiven-operator aiven/aiven-operator -``` + ```shell + helm install aiven-operator aiven/aiven-operator + ``` !!! note Installation will fail if webhooks are enabled and the CRDs for the cert-manager are not installed. + Alternatively, you can install without webhooks enabled by running: + ```shell + helm install aiven-operator aiven/aiven-operator --set webhooks.enabled=false + ``` -Verify the installation: +5\. To verify the installation, run: -```shell -helm status aiven-operator -``` + ```shell + helm status aiven-operator + ``` -The output is similar to the following: + The output is similar to the following: -```{ .shell .no-copy } -NAME: aiven-operator -LAST DEPLOYED: Fri Sep 10 15:23:26 2021 -NAMESPACE: default -STATUS: deployed -REVISION: 1 -TEST SUITE: None -``` + ```{ .shell .no-copy } + NAME: aiven-operator + LAST DEPLOYED: Fri Sep 10 15:23:26 2021 + NAMESPACE: default + STATUS: deployed + REVISION: 1 + TEST SUITE: None + ``` -It is also possible to install the operator without webhooks enabled: +6\. To verify the operator pod is running, run: -```shell -helm install aiven-operator aiven/aiven-operator --set webhooks.enabled=false -``` + ```bash + kubectl get pod -l app.kubernetes.io/name=aiven-operator + ``` -### Configuration Options +## Install without full cluster administrator access -Please refer to the [values.yaml](https://github.com/aiven/aiven-charts/blob/main/charts/aiven-operator/values.yaml) of the chart. +If you don't have the necessary permissions to create cluster-wide resources such as `ClusterRole` and `ClusterRoleBinding` when installing the Helm chart, +a cluster administrator can manually install these roles. +This ensures that the operator can function properly. -#### Install without full cluster administrator access +## Configuration options -If the person installing the Helm chart does not have the necessary permissions to create cluster-wide resources such as `ClusterRole` and `ClusterRoleBinding`, a cluster administrator can manually install these roles. This ensures that the operator can function properly. +Refer to the [values.yaml file](https://github.com/aiven/aiven-charts/blob/main/charts/aiven-operator/values.yaml) of the chart. -#### Restrict operator access to specific namespaces +### Restrict operator access to specific namespaces You can configure the operator to monitor resources within specific namespaces. -If the ClusterRole is enabled, it will be bound to the operator's `ServiceAccount` within each watched namespace using a `RoleBinding`. +If the `ClusterRole` is enabled, it's bound to the operator's `ServiceAccount` within each watched namespace using a `RoleBinding`. This setup grants the operator the permissions specified in the `ClusterRole`, but only within the context of the specific namespaces where the `RoleBinding` is created. - -## Uninstalling - -!!! important - Please see [this page](uninstalling.md) for more information. - -Find out the name of your deployment: - -```shell -helm list -``` - -The output has the name of each deployment similar to the following: - -```{ .shell .no-copy } -NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION -aiven-operator default 1 2021-09-09 10:56:14.623700249 +0200 CEST deployed aiven-operator-v0.1.0 v0.1.0 -aiven-operator-crds default 1 2021-09-09 10:56:05.736411868 +0200 CEST deployed aiven-operator-crds-v0.1.0 v0.1.0 -``` - -Remove the CRDs: - -```shell -helm uninstall aiven-operator-crds -``` - -The confirmation message is similar to the following: - -```{ .shell .no-copy } -release "aiven-operator-crds" uninstalled -``` - -Remove the operator: - -```shell -helm uninstall aiven-operator -``` - -The confirmation message is similar to the following: - -```{ .shell .no-copy } -release "aiven-operator" uninstalled -``` diff --git a/docs/docs/installation/kubectl.md b/docs/docs/installation/kubectl.md index a0674040..bf05871b 100644 --- a/docs/docs/installation/kubectl.md +++ b/docs/docs/installation/kubectl.md @@ -4,22 +4,16 @@ linkTitle: "Install with kubectl" weight: 15 --- -## Installing +# Install with kubectl -Before you start, make sure you have the [prerequisites](prerequisites.md). +The Aiven Operator for Kubernetes can be installed with kubectl. Before you start, make sure you have the [prerequisites](prerequisites.md). -All Aiven Operator for Kubernetes components can be installed from one YAML file that is uploaded for every release: +All Aiven Operator for Kubernetes components can be installed from one YAML file that is uploaded for every release. + +To install the latest version, run: ```shell kubectl apply -f https://github.com/aiven/aiven-operator/releases/latest/download/deployment.yaml ``` -By default the Deployment is installed into the `aiven-operator-system` namespace. - -## Uninstalling - -Assuming you installed version `vX.Y.Z` of the operator it can be uninstalled via - -```shell -kubectl delete -f https://github.com/aiven/aiven-operator/releases/download/vX.Y.Z/deployment.yaml -``` +By default the deployment is installed into the `aiven-operator-system` namespace. \ No newline at end of file diff --git a/docs/docs/installation/prerequisites.md b/docs/docs/installation/prerequisites.md index 22f96d85..bd5946d6 100644 --- a/docs/docs/installation/prerequisites.md +++ b/docs/docs/installation/prerequisites.md @@ -4,25 +4,19 @@ linkTitle: "Prerequisites" weight: 1 --- -The Aiven Operator for Kubernetes supports all major Kubernetes distributions, both locally and in the cloud. +# Prerequisites -Make sure you have the following: - -- To use the operator, you need admin access to a Kubernetes cluster. -- For playground usage you can use [kind](https://kind.sigs.k8s.io/) for example. -- For productive usage [Helm](https://helm.sh) is recommended. - -## [Cert Manager](https://cert-manager.io/) +The Aiven Operator for Kubernetes® supports all major Kubernetes distributions, both locally and in the cloud. -The Aiven Operator for Kubernetes uses `cert-manager` to configure the [service reference](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#service-reference) of our webhooks. - -Please follow the [installation instructions](https://cert-manager.io/docs/installation/helm/) on their website. +Make sure you have the following: -!!! note - This is not required in the Helm installation if you select to [disable webhooks](./helm.md), - but that is not recommended outside of playground use. +- Admin access to a Kubernetes cluster. +- [Cert manager installed](https://cert-manager.io/docs/installation/helm/): The operator uses this to configure the service reference of the webhooks. Webhooks are used for setting defaults + and enforcing invariants that are expected by the Aiven API and will lead to errors if ignored. - The Aiven Operator for Kubernetes uses webhooks for setting defaults - and enforcing invariants that are expected by the aiven API and will lead to errors if ignored. + !!! note + This is not required in the Helm installation if you select to [disable webhooks](./helm.md), + but that is not recommended outside of playground use. - In the future webhooks will also be used for conversion and supporting multiple CRD versions. +- For production usage, [Helm](https://helm.sh) is recommended. +- Optional: For playground usage, you can use [kind](https://kind.sigs.k8s.io/). diff --git a/docs/docs/installation/uninstalling.md b/docs/docs/installation/uninstalling.md index 7abaec65..cea526a6 100644 --- a/docs/docs/installation/uninstalling.md +++ b/docs/docs/installation/uninstalling.md @@ -4,14 +4,63 @@ linkTitle: "Uninstall" weight: 90 --- +# Uninstall + +Depending on your installation, you can uninstall the Aiven Operator using Helm or kubectl. + !!! danger - Uninstalling the Aiven Operator for Kubernetes can remove the resources created in Aiven, possibly resulting in data loss. + Uninstalling the Aiven Operator for Kubernetes can remove the resources created in Aiven, which can result in data loss. + +## Uninstall with Helm + +1. To get the name of your deployment, run: + +```shell +helm list +``` + +The output has the name of each deployment similar to the following: + +```{ .shell .no-copy } +NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION +aiven-operator default 1 2021-09-09 10:56:14.623700249 +0200 CEST deployed aiven-operator-v0.1.0 v0.1.0 +aiven-operator-crds default 1 2021-09-09 10:56:05.736411868 +0200 CEST deployed aiven-operator-crds-v0.1.0 v0.1.0 +``` + +2. To remove the CRDs, run: + +```shell +helm uninstall aiven-operator-crds +``` + +The confirmation message is similar to the following: -Depending on your installation, please follow one of: +```{ .shell .no-copy } +release "aiven-operator-crds" uninstalled +``` + +3. To remove the operator, run: + +```shell +helm uninstall aiven-operator +``` + +The confirmation message is similar to the following: + +```{ .shell .no-copy } +release "aiven-operator" uninstalled +``` -- [Helm](../installation/helm.md#uninstalling) -- [kubectl](../installation/kubectl.md#uninstalling) +## Uninstall with kubectl + +To uninstall the operator, run: + +```shell +kubectl delete -f https://github.com/aiven/aiven-operator/releases/download/vX.Y.Z/deployment.yaml +``` + +Where `vX.Y.Z` is the version of the operator you installed. ## Expired tokens @@ -21,11 +70,13 @@ The recommended approach to deal with that situation is to patch a valid token i ## Hanging deletions -To protect the Secrets that the operator is using from deletion, it adds the [finalizer](https://kubernetes.io/docs/concepts/overview/working-with-objects/finalizers/) `finalizers.aiven.io/needed-to-delete-services` to the Secret. +To protect the Secrets that the operator is using from deletion, it adds the [finalizer](https://kubernetes.io/docs/concepts/overview/working-with-objects/finalizers/) `finalizers.aiven.io/needed-to-delete-services` to the Secrets. This solves a race condition that happens when deleting a namespace, where there is a possibility of the Secret getting deleted before the resource that uses it. When the controller is deleted it may not cleanup the finalizers from all Secrets. -If there is a Secret with this finalizer blocking deletion of a namespace, you can remove the finalizer by running: +If there is a Secret with this finalizer blocking deletion of a namespace, you can remove the finalizer. + +To remove a finalizer, run: ```shell kubectl patch secret -p '{"metadata":{"finalizers":null}}' --type=merge -``` +``` \ No newline at end of file