Skip to content

Commit

Permalink
docs: update installation instructions
Browse files Browse the repository at this point in the history
  • Loading branch information
@staceysalamon-aiven
staceysalamon-aiven committed Oct 16, 2024
1 parent 6df5947 commit b8800ef
Show file tree
Hide file tree
Showing 6 changed files with 158 additions and 169 deletions.
49 changes: 16 additions & 33 deletions docs/docs/authentication.md
View file
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
[ ... ]
```
```
20 changes: 13 additions & 7 deletions docs/docs/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
147 changes: 54 additions & 93 deletions docs/docs/installation/helm.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
18 changes: 6 additions & 12 deletions docs/docs/installation/kubectl.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
28 changes: 11 additions & 17 deletions docs/docs/installation/prerequisites.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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/).
Loading

0 comments on commit b8800ef

Please sign in to comment.