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

Jump to bottom

docs(onboarding): Improve cluster onboarding documentation #655

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs(onboarding): Improve cluster onboarding documentation #655

wants to merge 2 commits into from

Conversation

uwe-mayer
Copy link
Contributor

Description

This aims to better define and outline the permission scopes needed to onboard a Cluster to Greenhouse

What type of PR is this? (check all applicable)

  • 🍕 Feature
  • 🐛 Bug Fix
  • 📝 Documentation Update
  • 🎨 Style
  • 🧑‍💻 Code Refactor
  • 🔥 Performance Improvements
  • ✅ Test
  • 🤖 Build
  • 🔁 CI
  • 📦 Chore (Release)
  • ⏩ Revert

Related Tickets & Documents

@uwe-mayer uwe-mayer requested a review from a team as a code owner October 23, 2024 09:05
@uwe-mayer uwe-mayer linked an issue Oct 23, 2024 that may be closed by this pull request
[Docs] - Improve cluster onboarding documentation #539
Open
@github-actions github-actions bot added the documentation Improvements or additions to documentation label Oct 23, 2024
@uwe-mayer
Update on conditions
347f492 
Signed-off-by: Uwe Mayer <[email protected]>
@uwe-mayer uwe-mayer changed the title chore(docs): Improve cluster onboarding documentation docs(onboarding): Improve cluster onboarding documentation Oct 23, 2024
kengou
kengou requested changes Oct 23, 2024
View reviewed changes
Copy link
Contributor

@kengou kengou left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm updating the greenhousectl cluster onboard ... just now. Please bear with me there will be just a slight change. Once finished I'm going to update your docs here

IvoGoman
IvoGoman reviewed Oct 25, 2024
View reviewed changes
docs/user-guides/cluster/onboarding.md

The command line tool requires access to both the Greenhouse **and** your Kubernetes cluster.
Hence, have the `kubeconfig` files for both clusters at hand. The `kubeconfig` file for the Greenhouse Kubernetes cluster can be downloaded via the Greenhouse dashboard: _Organization_ > _Clusters_ > _Access greenhouse cluster_.
Onboarding a `Cluster` to Greenhouse will require you to authenticate to two different kubernetes clusters via repsective `kubeconfig` files:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Onboarding a `Cluster` to Greenhouse will require you to authenticate to two different kubernetes clusters via repsective `kubeconfig` files:
Onboarding a `Cluster` to Greenhouse will require you to authenticate to two different Kubernetes clusters via respective `kubeconfig` files:

docs/user-guides/cluster/onboarding.md
For accessing the **Greenhouse Kubernetes cluster**, the `greenhousectl` will check whether your local kubectl is connected to the Greenhouse Kubernetes cluster. If not connected,
either the environment variables `KUBECONFIG` and `KUBECONTEXT` or the *greenhousectl* flags `--kubeconfig` and `--kubecontext`
must point to the respective Greenhouse kubeconfig.
- `greenhouse`: The cluster your Greenhouse installation is running on. You need `organization-admin` or `cluster-admin` priviledges.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- `greenhouse`: The cluster your Greenhouse installation is running on. You need `organization-admin` or `cluster-admin` priviledges.
- `greenhouse`: The cluster your Greenhouse installation is running on. You need `organization-admin` or `cluster-admin` privileges.

docs/user-guides/cluster/onboarding.md
either the environment variables `KUBECONFIG` and `KUBECONTEXT` or the *greenhousectl* flags `--kubeconfig` and `--kubecontext`
must point to the respective Greenhouse kubeconfig.
- `greenhouse`: The cluster your Greenhouse installation is running on. You need `organization-admin` or `cluster-admin` priviledges.
- `bootstrap`: The cluster you want to onboard. You need `system:masters` priviledges.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- `bootstrap`: The cluster you want to onboard. You need `system:masters` priviledges.
- `bootstrap`: The cluster you want to onboard. You need `system:masters` privileges.

docs/user-guides/cluster/onboarding.md

You need to have the `kubeconfig` files for both the `greenhouse` and the `bootstrap` cluster at hand. The `kubeconfig` file for the `greenhouse` cluster can be downloaded via the Greenhouse dashboard:

_Organization_ > _Clusters_ > _Access greenhouse cluster_.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
_Organization_ > _Clusters_ > _Access greenhouse cluster_.
_Organization_ > _Clusters_ > _Access Greenhouse cluster_.

docs/user-guides/cluster/onboarding.md
### Onboard

Since Greenhouse generates URLs which contain the cluster name, we highly recommend to choose a **short** cluster name.
In particular for <span style="color:red">Gardener Clusters</span> setting a short name is mandatory, because Gardener has very long cluster names, e.g. `garden-greenhouse--monitoring-external`.
For accessing the `greenhouse` cluster, the `greenhousectl` will expect your default kubernetes [`kubeconfig` file](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) and [`context`](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_config/kubectl_config_use-context/) to be set to `greenhouse`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
For accessing the `greenhouse` cluster, the `greenhousectl` will expect your default kubernetes [`kubeconfig` file](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) and [`context`](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_config/kubectl_config_use-context/) to be set to `greenhouse`.
For accessing the `greenhouse` cluster, the `greenhousectl` will expect your default Kubernetes [`kubeconfig` file](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) and [`context`](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_config/kubectl_config_use-context/) to be set to `greenhouse`.

kengou
kengou reviewed Oct 29, 2024
View reviewed changes
docs/user-guides/cluster/onboarding.md

```commandline
greenhousectl cluster bootstrap --bootstrap-kubeconfig <path/to/cluster-kubeconfig-file> --org <greenhouse-organization-name> --cluster-name <name>
greenhousectl cluster bootstrap --kubeconfig=<path/to/greenhouse-kubeconfig-file> --bootstrap-kubeconfig <path/to/bootstrap-kubeconfig-file> --org <greenhouse-organization-name> --cluster-name <name>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
greenhousectl cluster bootstrap --kubeconfig=<path/to/greenhouse-kubeconfig-file> --bootstrap-kubeconfig <path/to/bootstrap-kubeconfig-file> --org <greenhouse-organization-name> --cluster-name <name>
greenhousectl cluster bootstrap --kubeconfig=<path/to/bootstrap-kubeconfig-file> --greenhouse-kubeconfig <path/to/greenhouse-kubeconfig-file> --org <greenhouse-organization-name> --cluster-name <name>

kengou
kengou reviewed Oct 29, 2024
View reviewed changes
docs/user-guides/cluster/onboarding.md
For accessing the `greenhouse` cluster, the `greenhousectl` will expect your default kubernetes [`kubeconfig` file](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) and [`context`](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_config/kubectl_config_use-context/) to be set to `greenhouse`.
The easiest way for doing so is passing the `--kubeconfig` (and optionally `--kubecontext`) flag to your `greenhousectl` command.

The location of the `kubeconfig` file to the `bootstrap` cluster is passed via the `--bootstrap-kubeconfig` flag.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The location of the `kubeconfig` file to the `bootstrap` cluster is passed via the `--bootstrap-kubeconfig` flag.
The location of the `kubeconfig` file to the `bootstrap` cluster is passed via the `--kubeconfig` flag or via the `KUBECONFIG` enviorment variable

kengou
kengou reviewed Oct 29, 2024
View reviewed changes
docs/user-guides/cluster/onboarding.md
### Onboard

Since Greenhouse generates URLs which contain the cluster name, we highly recommend to choose a **short** cluster name.
In particular for <span style="color:red">Gardener Clusters</span> setting a short name is mandatory, because Gardener has very long cluster names, e.g. `garden-greenhouse--monitoring-external`.
For accessing the `greenhouse` cluster, the `greenhousectl` will expect your default kubernetes [`kubeconfig` file](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) and [`context`](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_config/kubectl_config_use-context/) to be set to `greenhouse`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
For accessing the `greenhouse` cluster, the `greenhousectl` will expect your default kubernetes [`kubeconfig` file](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) and [`context`](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_config/kubectl_config_use-context/) to be set to `greenhouse`.
For accessing the `greenhouse` cluster, the `greenhousectl` will expect you to pass [`kubeconfig` file](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) downloaded from Greenhouse dashboard via `--greenhouse-kubeconfig` flag

kengou
kengou reviewed Oct 29, 2024
View reviewed changes
docs/user-guides/cluster/onboarding.md
Since Greenhouse generates URLs which contain the cluster name, we highly recommend to choose a **short** cluster name.
In particular for <span style="color:red">Gardener Clusters</span> setting a short name is mandatory, because Gardener has very long cluster names, e.g. `garden-greenhouse--monitoring-external`.
For accessing the `greenhouse` cluster, the `greenhousectl` will expect your default kubernetes [`kubeconfig` file](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) and [`context`](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_config/kubectl_config_use-context/) to be set to `greenhouse`.
The easiest way for doing so is passing the `--kubeconfig` (and optionally `--kubecontext`) flag to your `greenhousectl` command.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The easiest way for doing so is passing the `--kubeconfig` (and optionally `--kubecontext`) flag to your `greenhousectl` command.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@kengou kengou kengou requested changes

@IvoGoman IvoGoman IvoGoman left review comments

Requested changes must be addressed to merge this pull request.

Assignees
No one assigned
Labels
documentation Improvements or additions to documentation
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

[Docs] - Improve cluster onboarding documentation
3 participants
@uwe-mayer @kengou @IvoGoman