Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updating clever operator - Installation instructions needed to be clearer #524

Merged
merged 11 commits into from
Feb 13, 2025
Merged

Updating clever operator - Installation instructions needed to be clearer #524

Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
35111a9
Adding Clever Operator
LostInBrittany Feb 5, 2025
444a854
Adding terms to Vale accepted words list, fixing lint errors
LostInBrittany Feb 5, 2025
2f484f6
Update content/guides/clever-operator.md
juliamrch Feb 7, 2025
2102eb0
Update content/guides/clever-operator.md
juliamrch Feb 7, 2025
23e30cb
Updating installation instructions
LostInBrittany Feb 10, 2025
6eff5bd
Merging and fixing Vale errors
LostInBrittany Feb 10, 2025
9afb6de
Merge branch 'main' into updating-clever-operator
juliamrch Feb 11, 2025
682c28d
Merge branch 'main' into updating-clever-operator
juliamrch Feb 13, 2025
323df85
Update clever-operator.md
juliamrch Feb 13, 2025
e5c67ec
style: use steps shortcode
juliamrch Feb 13, 2025
71c5233
fix: code blocks
juliamrch Feb 13, 2025
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
167 changes: 116 additions & 51 deletions content/guides/clever-operator.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,84 +50,152 @@

These prerequisites are essential for getting started with the Clever Operator, whether you're contributing to its development or deploying it in production.

## Getting the credentials

The Clever Operator requires configuration to connect to Clever Cloud's API and manage resources within your Kubernetes cluster. This configuration requires four credentials:

- _Consumer key_
- _Consumer Secret_
- _Token_
- _Secret_

To obtain them, you need to connect to the Clever Cloud API, that has an OAuth1 based authentication. As explained in the [Clever Cloud API Overview](/api/howto), you need to create an OAuth consumer token in the Clever Cloud console, use it to obtain the _Consumer key_ and the _Consumer Secret_, and do the OAuth authentication dance to get the _Token_ and _Secret_.


> #### This seems cumbersome, is there an easier way?
>
> Yes the OAuth dance is complex. If you want a simpler setup, there is a small application that you can deploy on Clever Cloud and that automates most of the pain away from you.
>
> The code and tutorial are on [https://github.com/CleverCloud/oauth-consumer-server](https://github.com/CleverCloud/oauth-consumer-server).

## Installation

The simplest ways to deploy the Clever Operator are either directly from Docker Hub or using the Helm chart.

### Deploying from DockerHub

Applying the deployment scripts:
{{% steps %}}

#### Clone the repository

```bash
kubectl apply -f https://raw.githubusercontent.com/CleverCloud/clever-operator/main/deployments/kubernetes/v1.24.0/10-custom-resource-definition.yaml
kubectl apply -f https://raw.githubusercontent.com/CleverCloud/clever-operator/main/deployments/kubernetes/v1.24.0/20-deployment.yaml
git clone https://github.com/CleverCloud/clever-operator/
```

#### Insert your credentials into the manifests

The manifests are on folder `/deployments/kubernetes/v1.24.0/`. Modify the `ConfigMap` object in file `/deployments/kubernetes/v1.24.0/:
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: clever-operator-configuration
namespace: clever-operator-system
data:
config.toml: |
[api]
endpoint = "https://api.clever-cloud.com/v2"
token = "<your_token>"
secret = "<your_secret>"
consumerKey = "<your_consumer_key>"
consumerSecret = "<your_consumer_secret>"
```

### Installing via Helm Chart
Replacing `<your_token>`, `<your_secret>`, `<your_consumer_key>` and `<your_consumer_secret>` by the credentials obtained in the precedent section.

1. Configuring `values.yaml` in `deployments/kubernetes/helm` with your values.
#### Apply the manifests to deploy the operator

2. Installing the chart:
```bash
helm install clever-operator -n clever-operator --create-namespace -f values.yaml .
```
```bash
kubectl apply -f /deployments/kubernetes/v1.24.0/10-custom-resource-definition.yaml
kubectl apply -f /deployments/kubernetes/v1.24.0/20-deployment.yaml
```

{{% /steps %}}

### Building from Source
### Installing via Helm Chart

{{% steps %}}

1. Cloning the repository:
#### Clone the repository

```bash
git clone https://github.com/CleverCloud/clever-operator.git
cd clever-operator
git clone https://github.com/CleverCloud/clever-operator/
```

2. Building the binary:
#### Configure your credentials in the `config` section of the file `values.yaml` in `deployments/kubernetes/helm`

```bash
make build
```yaml
config:
token: "<your_token>"
secret: "<your_secret>"
consumerKey: "<your_consumer_key>"
consumerSecret: "<your_consumer_secret>"
```

3. Running the operator:
Replacing `<your_token>`, `<your_secret>`, `<your_consumer_key>` and `<your_consumer_secret>` by the credentials obtained in the precedent section.

#### Install the chart:

```bash
target/release/clever-operator
helm install clever-operator -n clever-operator --create-namespace -f values.yaml .
```

### Building and Deploying the Docker Image
{{% /steps %}}

1. Building the Docker image:
### Building from Source

```bash
DOCKER_IMG=<your-registry>/<your-namespace>/clever-operator:latest make docker-build
```
{{% steps %}}

1. Pushing the image to your registry:
#### Clone the repository

```bash
DOCKER_IMG=<your-registry>/<your-namespace>/clever-operator:latest make docker-push
```
```bash
git clone https://github.com/CleverCloud/clever-operator.git
cd clever-operator
```

3. Updating the Kubernetes deployment script:

Modify `deployments/kubernetes/v1.24.0/20-deployment.yaml` to use your Docker image.
#### Insert your credentials into the manifests.

Check warning on line 156 in content/guides/clever-operator.md

View workflow job for this annotation

GitHub Actions / Run Vale Linter 

[vale] reported by reviewdog 🐶
[Google.HeadingPunctuation] Don't put a period at the end of a heading.

Raw Output:
{"message": "[Google.HeadingPunctuation] Don't put a period at the end of a heading.", "location": {"path": "content/guides/clever-operator.md", "range": {"start": {"line": 156, "column": 47}}}, "severity": "WARNING"}

The manifests are on folder `/deployments/kubernetes/v1.24.0/`. Modify the `ConfigMap` object in file `/deployments/kubernetes/v1.24.0/:

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: clever-operator-configuration
namespace: clever-operator-system
data:
config.toml: |
[api]
endpoint = "https://api.clever-cloud.com/v2"
token = "<your_token>"
secret = "<your_secret>"
consumerKey = "<your_consumer_key>"
consumerSecret = "<your_consumer_secret>"
```

4. Deploying to Kubernetes:
```bash
make deploy-kubernetes
```
Replacing `<your_token>`, `<your_secret>`, `<your_consumer_key>` and `<your_consumer_secret>` by the credentials obtained in the precedent section.

#### Build the binary:

## Configuration
```bash
make build
```

#### Running the operator:

The Clever Operator requires configuration to connect to Clever Cloud's API and manage resources within your Kubernetes cluster. Configuration options are available at two levels: global (applies to all namespaces) and namespace-specific.
```bash
target/release/clever-operator
```

{{% /steps %}}

## Configuration

For details on how to obtain these credentials, follow the instructions on the [How to obtain the credentials for the Clever Operator](./credentials.md) document.
Configuration options are available at two levels: global (applies to all namespaces) and namespace-specific.

### Global Configuration

Global configuration settings apply across all namespaces and are defined via environment variables or configuration files.
Global configuration settings apply across all namespaces. Global configuration can be provided through a `ConfigMap`, a `Secret` or by the environment.

Check warning on line 198 in content/guides/clever-operator.md

View workflow job for this annotation

GitHub Actions / Run Vale Linter 

[vale] reported by reviewdog 🐶
[Google.Passive] In general, use active voice instead of passive voice ('be provided').

Raw Output:
{"message": "[Google.Passive] In general, use active voice instead of passive voice ('be provided').", "location": {"path": "content/guides/clever-operator.md", "range": {"start": {"line": 198, "column": 85}}}, "severity": "INFO"}

- **Environment Variables:**

Expand Down Expand Up @@ -156,19 +224,16 @@
apiVersion: v1
kind: Secret
metadata:
name: clever-operator
namespace: my-namespace
data:
config: |-
api:
endpoint: "https://api.clever-cloud.com/v2"
token: "<your-api-token>"
secret: "<your-api-secret>"
consumerKey: "<your-consumer-key>"
consumerSecret: "<your-consumer-secret>"
proxy:
host: "proxy.example.com"
port: 8080
name: clever-secret
namespace: <your_namespace>
stringData:
config: |
[api]
endpoint = "https://api.clever-cloud.com/v2"
token = <your_token>
secret = <your_secret>
consumerKey = <your_consumer_key>
consumerSecret = <your_consumer_secret>
```

- **Applying the Configuration:** Apply the Secret to your namespace:
Expand Down
Loading