From 41779bb4767e04f6d3d8b9bd5636df680483f1bb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Eneko=20Fern=C3=A1ndez?=
<12957664+enekofb@users.noreply.github.com>
Date: Thu, 2 Nov 2023 15:58:41 +0000
Subject: [PATCH] Add cli docs eneko (#4115)
* reviewed heading and pre-requirements
* added initial review
* refactoring dashboard access
* ready for a second review
* added externalDNS link
---
.../install-enterprise-cli.mdx | 364 +++++-------------
1 file changed, 86 insertions(+), 278 deletions(-)
diff --git a/website/docs/enterprise/getting-started/install-enterprise-cli.mdx b/website/docs/enterprise/getting-started/install-enterprise-cli.mdx
index 060f3760a1..2462527f22 100644
--- a/website/docs/enterprise/getting-started/install-enterprise-cli.mdx
+++ b/website/docs/enterprise/getting-started/install-enterprise-cli.mdx
@@ -5,101 +5,139 @@ toc_max_heading_level: 4
---
import TierLabel from "../../_components/TierLabel";
+import AlphaWarning from "../../_components/_alpha_warning.mdx";
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
# Install Weave GitOps Enterprise via CLI
-Weave GitOps Enterprise provides a streamlined method for its installation, employing the `gitops-ee bootstrap` command. This command acts as a wizard-like interface, simplifying the installation process by guiding users through each step of the configuration. For those seeking advanced customization, the flexibility to fine-tune the Weave GitOps Enterprise Helm release directly is also available.
+
-## Prerequisites
+You could install Weave GitOps Enterprise `gitops-ee bootstrap` which streamlines the installation process. It has two main modes:
-Before you start with the installation process, please make sure the following pre-requisites are there and available.
+1. `Interactive` or Wizard mode for guiding you step-by-step through the process until Weave GitOps Enterprise is up and running. Ideal for your first installation.
+2. `Non-interactive` or automated mode where the process will be executed via configuration. Ideal for your automated workflows.
-* Management Cluster, a kubernetes cluster with a kubeconfig that has admin permissions to be able to create resources.
-* Git Repository to be used as the repository of the WeaveGitOps Enterprise repo. At this point, we require that you have ssh access to your git repository.
-* Flux binary to be installed locally to be used in reconciling sources, Kustomizations, HelmReleases
-* Flux installed on the Management cluster using `flux bootstrap`.
-:::info
-Please follow flux guide here: [https://fluxcd.io/flux/installation/bootstrap/](https://fluxcd.io/flux/installation/bootstrap/)
-:::
+For those seeking advanced customization, the flexibility to fine-tune [Weave GitOps Enterprise manual install](../install-enterprise) is also available.
-* Entitlment installed in the management cluster.
-:::info
-To get the entitlement secret please contact *sales@weave.works*, then apply it on your management cluster with the name `weave-gitops-enterprise-credentials` under `flux-system` namespace.
-:::
+## Prerequisites
+
+Before you start make sure the following requirements are met:
+
+- [ ] **Management Cluster**: a Kubernetes cluster with a Kubeconfig that has Admin permissions to be able to create resources.
+- [ ] **Git Repository with SSH access**: this is the configuration repo that WeaveGitOps will use to sync configuration manifests from.
+- [ ] **Flux CLI**: is [installed](https://fluxcd.io/flux/installation/#install-the-flux-cli) locally. It will be used for reconciling Flux resources.
+- [ ] **Flux Bootstrapped** in your Management cluster via ssh. See [Flux Bootstrap](https://fluxcd.io/flux/installation/bootstrap/generic-git-server/) for more info.
+- [ ] **Weave GitOps Enterprise Entitlements** are installed in the management cluster. Contact [Sales](../help-and-support/) for help on getting them.
## Getting Started
#### Install `gitops-ee` CLI (> v0.35)
-Weave GitOps Enterprise Bootstrap functionality is available on Weave GitOps Enterprise CLI starting from version x.x.x. If you haven't already, please install the latest `gitops-ee` CLI using this command.
+Weave GitOps Enterprise Bootstrap functionality is available on Weave GitOps Enterprise CLI starting from version v0.35. If you haven't already, please install the latest `gitops-ee` CLI using this command.
+
```bash
brew install weaveworks/tap/gitops-ee
```
#### Bootstrap Weave GitOps Enterprise
+
Please use the following command to start the installation wizard of Weave GitOps Enterprise.
-```bash
-gitops-ee bootstrap
-```
+
+
+
+
+
+ ```bash
+
+ gitops-ee bootstrap
-The bootstrap wizard will take you step-by-step into configuring Weave GitOps Enterprise. To understand more about the CLI configurations experience, check the below sections [here](#cli-configurations).
+ ```
-## Understanding `gitops-ee bootstrap`
-### Overview
+ The bootstrap wizard will take you step-by-step into configuring Weave GitOps Enterprise. To understand more about the CLI configurations experience, check the below sections [here](#cli-configurations).
-`gitops-ee bootstrap` command is a wizard-like command line that helps you to install Weave GitOps Enterprise on their management cluster by guiding them step by step to configure it.
+
-The following are the steps the wizard will take you through it.
+
-1. [Verifying Entitlement](#verifying-entitlement): Verify entitlement secret content (username, password, entitlement)
-2. [Verifying flux](#verifying-flux): Verify flux installation on management cluster
-4. [Selecting WGE version](#selecting-wge-version): from the latest 3 available releases
-5. [Create admin credentials](#create-admin-credentials): create admin secret with username and password to be able to access the dashboard
-6. [Select the domain](#select-the-domain): choose between 2 methods to access the dashboard either locally or via external domain
-7. [Access the dashboard](#access-the-dashboard): via the link from the installation success message
+ You could run the bootstrap command in non-interactive mode by providing the required configurations as flags. The following gives you an example to get started that you could adapt to your own context
+
+ ```bash
+ gitops-ee bootstrap \
+ --kubeconfig="~/.kube/config" \ # (optional) Management cluster configuration. If not set default kubeconfig resolution is used.
+ --private-key="~/.ssh/id_rsa" --private-key-password="" \ # Git repository SSH configuration
+ --version="0.33.0" \ # version to install
+ --domain-type="localhost" \ # how to expose the dashboard
+ --username=wego-admin --password=admin123 \ # emergency user configuration
+ --discovery-url="" --client-id="weave-gitops-enterprise" --client-secret="changeme" \ # (optional) OIDC configuration
+ ```
+ For more information about the CLI configurations, check the below sections [here](#cli-configurations)
+
+
+
+
+
+
+## Appendix
+
+### Appendix I: Understanding `gitops-ee bootstrap`
+
+`gitops-ee bootstrap` is a workflow that will take you through the following stages:
+
+1. [Verify Flux](#verifying-flux): verify Flux installation on the Management cluster.
+2. [Verify Entitlement](#verifying-entitlement): verify the Entitlements secret content (username, password, entitlement).
+3. [Configure Git Access](#configure-git-access): configure the access to your configuration repo.
+4. [Select WGE version](#selecting-wge-version): from the latest 3 available releases.
+5. [Create Cluster User](#create-cluster-user): create a Secret with the username and password for the emergency cluster user.
+6. [Configure Dashboard Access](#configure-dashboard-access): choose between 2 methods to access the dashboard either local or external.
+7. [Access the dashboard](#access-the-dashboard): via the link from the installation success message.
8. (Optional) [Configure OIDC](#configure-oidc): to enable login to dashboard via OIDC providers.
-### Verifying Entitlement
+#### Verify Entitlement
-Weave GitOps Enterprise Entitlement is your obtained license to use our product. The entitlement file is a kubernetes secret that contains your licence. The bootstrap CLI will check if the entitlement manifest exists on the management cluster, and it will check if it has valid content and the entitlement is not expired.
+Weave GitOps Enterprise Entitlement is your obtained license to use our product. The Entitlements file is a Kubernetes secret that contains your licence.
+`Bootstrapping` checks that the secret exists on the management cluster, and that it is valid will check if it has valid content and the entitlement is not expired.
To get the entitlement secret please contact *sales@weave.works*, then apply it on your management cluster with the name `weave-gitops-enterprise-credentials` under `flux-system` namespace.
-### Verifying flux
+#### Verify Flux
Weave GitOps Enterprise runs on top of flux, the bootstrap CLI will check if flux is installed on the management cluster, and it will verify that it has the right version with valid git repository setup, and it is able to reconcile flux components properly.
If flux is installed, but doesn't have a valid installation, the bootstrap CLI will terminate pending the fix or uninstall of current flux installation.
If flux is not installed at all, the bootstrap CLI offers the option to bootstrap flux.
-### Providing GitRepository Authentication
+#### Configure Git Access
+
In order for `gitops-ee bootstrap` to push WGE resources to the management cluster's git repository, you will be prompted to provide the private key used to access your repo via ssh. If the private key is encrypted, you will also be asked to provide the private key password.
:::info
Disclaimer: The bootstrap CLI will ONLY use the private key to push WGE resources to your repo, and won't use it in any other way that can comprimise your repo or clusters security.
:::
-### Selecting WGE version
+#### Select WGE version
+
The bootstrap CLI will prompt you to choose from the latest 3 versions of Weave GitOps Enterprise.
-### Create admin credentials
+#### Create Cluster User
+
You will be prompt to provide admin username and password, which will be used to access the dashboard. This will create admin secret with the credentials. If you already have previous admin credentials on your cluster, the installation will prompt you if you want to continue with the old credentials or exit and revoke them and re-run the installation.
-### Select the domain
-To access Weave GitOps Enterprise dashboard, you have one of 2 options:
-##### via localhost
-This requires no pre-requisites and more suitable for testing on your local or development environment, or air-gapped environments.
+#### Configure Dashboard Access
+To access Weave GitOps Enterprise dashboard, you have the two following options available:
+1. **Service**: this option is called `localhost` in the cli and the dashboard will be available through a [ClusterIP Service](https://kubernetes.io/docs/concepts/services-networking/service/#type-clusterip).
+2. **Ingress**: this option is called `externaldns` the dashboard will be available through an [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) with the following considerations:
+ - An Ingress controller needs to exist.
+ - A host-based ingress will be created of the ingress class `public-nginx`.
+ - An [ExternalDNS](https://github.com/kubernetes-sigs/external-dns) annotation will be added with the value of the provided domain.
-##### via External Domain
-This is more suitable for production environments where multiple users are going to access the dashboard. However, this will require extrnal dns to be set up and configured for the domain to be accessible.
-:::tip
-While there are multiple ways to setup and configure external dns. You can find a full example on how to setup it for multiple cloud providers [here](#external-dns)
-:::
+#### Access the dashboard
-### Access the dashboard
After installation is successful. The CLI will print out the URL where you can access the dashboard.
-### (Optional) Configure OIDC
+#### (Optional) Configure OIDC
+
OIDC configuration will enable you to login with OIDC provider beside, or instead of the admin credentials. Afte the installation is complete, you will be prompt if you want to configure OIDC access. If you don't want to set it up right away, you can do it later by running `gitops-ee bootstrap auth --type=oidc` command.
To configure OIDC access, you will be asked to provide the following values:
@@ -110,11 +148,9 @@ To configure OIDC access, you will be asked to provide the following values:
Please don't forget to add a new static-client on your OIDC provider settings with the redirectURI `your-domain/oauth2/callback` for example `http://localhost:3000/oauth2/callback`
:::
-## Appendix
-
-### CLI configurations
+### Appendix II: CLI configurations
-- `--kube-config`: allows to choose the kubeconfig for your cluster, default would be ~/.kube/config
+- `--kube-config`: allows to choose the Kubeconfig for your cluster, default would be ~/.kube/config
- `-d`, `--domain externaldns`: indicate the domain to use in case of using externaldns
- `-t`, `--domain-type`: dashboard domain type: could be 'localhost' or 'externaldns'
- `-h`, `--help`: help for bootstrap
@@ -123,231 +159,3 @@ Please don't forget to add a new static-client on your OIDC provider settings wi
- `-c`, `--private-key-password`: Private key password. If the private key is encrypted using password
- `-u`, `--username`: Dashboard admin username
- `-v`, `--version`: Weave GitOps Enterprise version to install
-
-
-#### External DNS
-
-[External DNS](https://github.com/kubernetes-sigs/external-dns) for Kubernetes is a tool that automates the management of external DNS records.
-It allows Kubernetes services to be exposed to the internet with a DNS entry that corresponds to the service's name.
-
-There are several implementations of External DNS available with specific DNS providers (e.g., AWS Route 53, Google Cloud DNS, Azure DNS, etc.).
-
-Some popular implementations include:
-- kube-dns: Integrates with CoreDNS and is a common choice for Kubernetes clusters.
-- AWS Route 53 External DNS: Specifically for AWS Route 53.
-- GCP External DNS: For Google Cloud DNS.
-- Azure External DNS: For Azure DNS.
-
-Learn how to deploy External DNS into your cluster [here](https://github.com/kubernetes-sigs/external-dns?tab=readme-ov-file#deploying-to-a-cluster)
-
-[Full tutorial to use External DNS with AWS Route 53](https://kubernetes-sigs.github.io/aws-load-balancer-controller/v2.5/guide/integrations/external_dns/)
-
-After configuring your provider to use ExternalDNS, The following example is a follow-up on the previous tutorial is the manifests that need to be deployed to the cluster with the following structure:
-
-Expand to see the files structure
-
-```bash
-.
-├── cluster-role-binding.yaml
-├── cluster-role.yaml
-├── deployment.yaml
-├── kustomization.yaml
-├── ingress-nginx.yaml
-└── namespace.yaml
-```
-
-Expand to see example Kustomization file content
-
-```yaml
-apiVersion: kustomize.config.k8s.io/v1beta1
-kind: Kustomization
-resources:
-- namespace.yaml
-- deployment.yaml
-- cluster-role.yaml
-- cluster-role-binding.yaml
-- ingress-nginx.yaml
-```
-Expand to see example `namespace.yaml` file content
-
-```yaml
-apiVersion: v1
-kind: Namespace
-metadata:
- name: external-dns
-```
-Expand to see example `cluster-role.yaml` file content
-
-```yaml
-apiVersion: rbac.authorization.k8s.io/v1
-kind: ClusterRole
-metadata:
- name: external-dns
- labels:
- app.kubernetes.io/name: external-dns
-rules:
- - apiGroups: [""]
- resources: ["services","endpoints","pods","nodes"]
- verbs: ["get","watch","list"]
- - apiGroups: ["extensions","networking.k8s.io"]
- resources: ["ingresses"]
- verbs: ["get","watch","list"]
-```
-
-Expand to see example `cluster-role-binding.yaml` file content
-
-```yaml
-apiVersion: rbac.authorization.k8s.io/v1
-kind: ClusterRoleBinding
-metadata:
- name: external-dns-viewer
- labels:
- app.kubernetes.io/name: external-dns
-roleRef:
- apiGroup: rbac.authorization.k8s.io
- kind: ClusterRole
- name: external-dns
-subjects:
- - kind: ServiceAccount
- name: external-dns
- namespace: external-dns
-```
-
-Expand to see example `deployment.yaml` file content
-
-```yaml
-apiVersion: apps/v1
-kind: Deployment
-metadata:
- name: external-dns
- namespace: external-dns
- labels:
- app.kubernetes.io/name: external-dns
-spec:
- strategy:
- type: Recreate
- selector:
- matchLabels:
- app.kubernetes.io/name: external-dns
- template:
- metadata:
- labels:
- app.kubernetes.io/name: external-dns
- spec:
- serviceAccountName: external-dns
- containers:
- - name: external-dns
- image: k8s.gcr.io/external-dns/external-dns:v0.11.0
- args:
- - --source=service
- - --source=ingress
- - --domain-filter= # will make ExternalDNS see only the hosted zones matching provided domain, omit to process all available hosted zones. example (mydomain.com)
- - --provider=aws
- - --policy=sync # would allow ExternalDNS to delete records, use upsert-only to prevent ExternalDNS from deleting any records
- - --aws-zone-type=public # only look at public hosted zones (valid values are public, private or no value for both)
- - --registry=txt
- - --txt-owner-id=cluster-${CLUSTER_NAME}
- env:
- - name: AWS_DEFAULT_REGION
- value: # select the default aws-region (example: eu-north-1)
-```
-
-Expand to see example `ingress-nginx.yaml` file content
-
-```yaml
-apiVersion: source.toolkit.fluxcd.io/v1beta2
-kind: HelmRepository
-metadata:
- name: ingress-nginx
- namespace: flux-system
-spec:
- interval: 1m0s
- timeout: 1m0s
- url: "https://kubernetes.github.io/ingress-nginx"
----
-apiVersion: helm.toolkit.fluxcd.io/v2beta1
-kind: HelmRelease
-metadata:
- labels:
- weave.works/applied-layer: layer-1
- name: ingress-nginx
- namespace: flux-system
-spec:
- chart:
- spec:
- chart: ingress-nginx
- sourceRef:
- apiVersion: source.toolkit.fluxcd.io/v1beta2
- kind: HelmRepository
- name: ingress-nginx
- namespace: flux-system
- version: 4.2.5
- install:
- crds: CreateReplace
- createNamespace: true
- interval: 1m0s
- targetNamespace: flux-system
- upgrade:
- crds: CreateReplace
- values:
- controller:
- ingressClassResource:
- enabled: true
- name: public-nginx
- default: false
- controllerValue: "k8s.io/public-ingress-nginx"
- ingressClass: public-nginx
- service:
- annotations:
- service.beta.kubernetes.io/aws-load-balancer-ssl-cert: ${SSL_CERTIFICATE_ARN}
- service.beta.kubernetes.io/aws-load-balancer-type: nlb
- service.beta.kubernetes.io/aws-load-balancer-internal: "false"
- targetPorts:
- http: http
- https: http
-```
-
-Expand to see ingress configurations
-
-```yaml
-ingress:
- annotations:
- external-dns.alpha.kubernetes.io/hostname: mydomain.com
- className: public-nginx
- enabled: true
- hosts:
- - host: mydomain.com
- paths:
- - path: /
- pathType: ImplementationSpecific
-```
-
-