diff --git a/README.md b/README.md index 5807c16aa..3e1f585d0 100644 --- a/README.md +++ b/README.md @@ -57,8 +57,10 @@ We recommend running this command as an unprivileged user, that is inside the [d - [Apply playground](#apply-playground) - [Apply via Docker (local cluster)](#apply-via-docker-local-cluster) - [Apply via kubectl (remote cluster)](#apply-via-kubectl-remote-cluster) - - [Additional parameters](#additional-parameters) + - [Configuration](#configuration) + - [Overview of all CLI and config options](#overview-of-all-cli-and-config-options) - [Configuration file](#configuration-file) + - [Print all CLI parameters](#print-all-cli-parameters) - [Deploy Ingress Controller](#deploy-ingress-controller) - [Deploy Ingresses](#deploy-ingresses) - [Deploy GitOps operators](#deploy-gitops-operators) @@ -71,6 +73,7 @@ We recommend running this command as an unprivileged user, that is inside the [d - [MailHog](#mailhog) - [External Mailserver](#external-mailserver) - [Secrets Management](#secrets-management) + - [Certificate Management](#certificate-management) - [Remove playground](#remove-playground) - [Running on Windows or Mac](#running-on-windows-or-mac) - [Mac and Windows WSL](#mac-and-windows-wsl) @@ -188,7 +191,7 @@ There are several options for running the container: * For local k3d cluster, we recommend running the image as a local container via `docker` * For remote clusters (e.g. on GKE) you can run the image inside a pod of the target cluster via `kubectl`. -All options offer the same parameters, see [below](#additional-parameters). +All options offer the same parameters, see [below](#overview-of-all-cli-and-config-options). #### Apply via Docker (local cluster) @@ -246,15 +249,259 @@ kubectl delete clusterrolebinding/gitops-playground-job-executer \ In general `docker run` should work here as well. But GKE, for example, uses gcloud and python in their kubeconfig. Running inside the cluster avoids these kinds of issues. -#### Additional parameters - -The following describes more parameters and use cases. - -You can get a full list of all options like so: - -```shell -docker run -t --rm ghcr.io/cloudogu/gitops-playground --help -``` +#### Configuration + +The following describes how to configure GOP. + +You can configure GOP using CLI params, config file and/or config map. +Config file and map have the same format and offer a [schema file](https://raw.githubusercontent.com/cloudogu/gitops-playground/main/docs/configuration.schema.json). +See [here](#configuration-file). +You can also find a list of all CLI/config options [here](#overview-of-all-cli-and-config-options). + +**Configuration precedence (highest to lowest):** +1. Command-line parameters +2. Configuration files (`--config-file`) +3. Config maps (`--config-map`) + +That is, if you pass a param via CLI, for example, it will overwrite the corresponding value in the configuration. + +##### Overview of all CLI and config options + +- [Registry](#registry) +- [Jenkins](#jenkins) +- [Multitenant](#multitenant) +- [SCMM](#scmm) +- [Application](#application) +- [Images](#images) +- [Features](#features) + - [ArgoCD](#argocd) + - [Mail](#mail) + - [Monitoring](#monitoring) + - [Secrets](#secrets) + - [Ingress Nginx](#ingress-nginx) + - [Cert Manager](#cert-manager) +- [Content](#content) + +###### Registry + +| CLI | Config | Default | Type | Description | +|-----|--------|---------|------|-------------| +| `--registry` | `registry.active` | `false` | Boolean | Installs a simple cluster-local registry for demonstration purposes. Warning: Registry does not provide authentication! | +| `--internal-registry-port` | `registry.internalPort` | `30000` | Integer | Port of registry registry. Ignored when a registry*url params are set | +| `--registry-url` | `registry.url` | `''` | String | The url of your external registry, used for pushing images | +| `--registry-path` | `registry.path` | `''` | String | Optional when registry-url is set | +| `--registry-username` | `registry.username` | `''` | String | Optional when registry-url is set | +| `--registry-password` | `registry.password` | `''` | String | Optional when registry-url is set | +| `--registry-proxy-url` | `registry.proxyUrl` | `''` | String | The url of your proxy-registry. Used in pipelines to authorize pull base images | +| `--registry-proxy-username` | `registry.proxyUsername` | `''` | String | Use with registry-proxy-url, added to Jenkins as credentials and created as pull secrets | +| `--registry-proxy-password` | `registry.proxyPassword` | `''` | String | Use with registry-proxy-url, added to Jenkins as credentials and created as pull secrets | +| `--registry-username-read-only` | `registry.readOnlyUsername` | `''` | String | Optional alternative username for registry-url with read-only permissions | +| `--registry-password-read-only` | `registry.readOnlyPassword` | `''` | String | Optional alternative password for registry-url with read-only permissions | +| `--create-image-pull-secrets` | `registry.createImagePullSecrets` | `false` | Boolean | Create image pull secrets for registry and proxy-registry for all GOP namespaces | +| - | `registry.helm.chart` | `'docker-registry'` | String | Name of the Helm chart | +| - | `registry.helm.repoURL` | `'https://helm.twun.io'` | String | Repository url from which the Helm chart should be obtained | +| - | `registry.helm.version` | `'2.2.3'` | String | The version of the Helm chart to be installed | +| - | `registry.helm.values` | `[:]` | Map | Helm values of the chart | + +###### Jenkins + +| CLI | Config | Default | Type | Description | +|-----|--------|---------|------|-------------| +| `--jenkins` | `jenkins.active` | `false` | Boolean | Installs Jenkins as CI server | +| `--jenkins-skip-restart` | `jenkins.skipRestart` | `false` | Boolean | Skips restarting Jenkins after plugin installation | +| `--jenkins-skip-plugins` | `jenkins.skipPlugins` | `false` | Boolean | Skips plugin installation | +| `--jenkins-url` | `jenkins.url` | `''` | String | The url of your external jenkins | +| `--jenkins-username` | `jenkins.username` | `'admin'` | String | Mandatory when jenkins-url is set | +| `--jenkins-password` | `jenkins.password` | `'admin'` | String | Mandatory when jenkins-url is set | +| `--jenkins-metrics-username` | `jenkins.metricsUsername` | `'metrics'` | String | Mandatory when jenkins-url is set and monitoring enabled | +| `--jenkins-metrics-password` | `jenkins.metricsPassword` | `'metrics'` | String | Mandatory when jenkins-url is set and monitoring enabled | +| `--maven-central-mirror` | `jenkins.mavenCentralMirror` | `''` | String | URL for maven mirror, used by applications built in Jenkins | +| `--jenkins-additional-envs` | `jenkins.additionalEnvs` | `[:]` | Map | Set additional environments to Jenkins | +| - | `jenkins.helm.chart` | `'jenkins'` | String | Name of the Helm chart | +| - | `jenkins.helm.repoURL` | `'https://charts.jenkins.io'` | String | Repository url from which the Helm chart should be obtained | +| - | `jenkins.helm.version` | `'5.8.43'` | String | The version of the Helm chart to be installed | +| - | `jenkins.helm.values` | `[:]` | Map | Helm values of the chart | + +###### Multitenant + +| CLI | Config | Default | Type | Description | +|-----|--------|---------|------|-------------| +| `--dedicated-internal` | `multiTenant.internal` | `false` | Boolean | SCM for Central Management is running on the same cluster | +| `--dedicated-instance` | `multiTenant.useDedicatedInstance` | `false` | Boolean | Toggles the Dedicated Instances Mode | +| `--central-scm-url` | `multiTenant.centralScmUrl` | `''` | String | URL for the centralized Management Repo | +| `--central-scm-username` | `multiTenant.username` | `''` | String | CENTRAL SCMM USERNAME | +| `--central-scm-password` | `multiTenant.password` | `''` | String | CENTRAL SCMM Password | +| `--central-argocd-namespace` | `multiTenant.centralArgocdNamespace` | `'argocd'` | String | CENTRAL Argocd Repo Namespace | +| `--central-scm-namespace` | `multiTenant.centralSCMamespace` | `'scm-manager'` | String | Central SCM namespace | + +###### SCMM + +| CLI | Config | Default | Type | Description | +|-----|--------|---------|------|-------------| +| `--scmm-skip-restart` | `scmm.skipRestart` | `false` | Boolean | Skips restarting SCM-Manager after plugin installation | +| `--scmm-skip-plugins` | `scmm.skipPlugins` | `false` | Boolean | Skips plugin installation | +| `--scmm-url` | `scmm.url` | `''` | String | The host of your external scm-manager | +| `--scmm-username` | `scmm.username` | `'admin'` | String | Mandatory when scmm-url is set | +| `--scmm-password` | `scmm.password` | `'admin'` | String | Mandatory when scmm-url is set | +| `--scm-root-path` | `scmm.rootPath` | `'repo'` | String | Sets the root path for the Git Repositories | +| `--scm-provider` | `scmm.provider` | `'scm-manager'` | String | Sets the scm Provider. Possible Options are "scm-manager" and "gitlab" | +| - | `scmm.helm.chart` | `'scm-manager'` | String | Name of the Helm chart | +| - | `scmm.helm.repoURL` | `'https://packages.scm-manager.org/repository/helm-v2-releases/'` | String | Repository url from which the Helm chart should be obtained | +| - | `scmm.helm.version` | `'3.10.2'` | String | The version of the Helm chart to be installed | +| - | `scmm.helm.values` | `[:]` | Map | Helm values of the chart | + +###### Application + +| CLI | Config | Default | Type | Description | +|-----|--------|---------|------|-------------| +| `--config-file` | - | `''` | String | Config file path | +| `--config-map` | - | `''` | String | Config map name | +| `-d, --debug` | `application.debug` | - | Boolean | Enable debug mode | +| `-x, --trace` | `application.trace` | - | Boolean | Enable trace mode | +| `--output-config-file` | `application.outputConfigFile` | `false` | Boolean | Output configuration file | +| `-v, --version` | `application.versionInfoRequested` | `false` | Boolean | Display version and license info | +| `-h, --help` | `application.usageHelpRequested` | `false` | Boolean | Display help message | +| `--remote` | `application.remote` | `false` | Boolean | Expose services as LoadBalancers | +| `--insecure` | `application.insecure` | `false` | Boolean | Sets insecure-mode in cURL which skips cert validation | +| `--openshift` | `application.openshift` | `false` | Boolean | When set, openshift specific resources and configurations are applied | +| `--username` | `application.username` | `'admin'` | String | Set initial admin username | +| `--password` | `application.password` | `'admin'` | String | Set initial admin passwords | +| `-y, --yes` | `application.yes` | `false` | Boolean | Skip confirmation | +| `--name-prefix` | `application.namePrefix` | `''` | String | Set name-prefix for repos, jobs, namespaces | +| `--destroy` | `application.destroy` | `false` | Boolean | Unroll playground | +| `--pod-resources` | `application.podResources` | `false` | Boolean | Write kubernetes resource requests and limits on each pod | +| `--git-name` | `application.gitName` | `'Cloudogu'` | String | Sets git author and committer name used for initial commits | +| `--git-email` | `application.gitEmail` | `'hello@cloudogu.com'` | String | Sets git author and committer email used for initial commits | +| `--base-url` | `application.baseUrl` | `''` | String | The external base url (TLD) for all tools | +| `--url-separator-hyphen` | `application.urlSeparatorHyphen` | `false` | Boolean | Use hyphens instead of dots to separate application name from base-url | +| `--mirror-repos` | `application.mirrorRepos` | `false` | Boolean | Changes the sources of deployed tools so they work in air-gapped environments | +| `--skip-crds` | `application.skipCrds` | `false` | Boolean | Skip installation of CRDs | +| `--namespace-isolation` | `application.namespaceIsolation` | `false` | Boolean | Configure tools to work with given namespaces only | +| `--netpols` | `application.netpols` | `false` | Boolean | Sets Network Policies | + +###### Images + +| CLI | Config | Default | Type | Description | +|-----|--------|---------|------|-------------| +| `--kubectl-image` | `images.kubectl` | `"bitnamilegacy/kubectl:1.29"` | String | Sets image for kubectl | +| `--helm-image` | `images.helm` | `"ghcr.io/cloudogu/helm:3.16.4-1"` | String | Sets image for helm | +| `--kubeval-image` | `images.kubeval` | `"ghcr.io/cloudogu/helm:3.16.4-1"` | String | Sets image for kubeval | +| `--helmkubeval-image` | `images.helmKubeval` | `"ghcr.io/cloudogu/helm:3.16.4-1"` | String | Sets image for helmkubeval | +| `--yamllint-image` | `images.yamllint` | `"cytopia/yamllint:1.25-0.7"` | String | Sets image for yamllint | +| `--nginx-image` | `images.nginx` | `''` | String | Sets image for nginx | +| `--petclinic-image` | `images.petclinic` | `'eclipse-temurin:17-jre-alpine'` | String | Sets image for petclinic | +| `--maven-image` | `images.maven` | `''` | String | Sets image for maven | + +###### ArgoCD + +| CLI | Config | Default | Type | Description | +|-----|--------|---------|------|-------------| +| `--argocd` | `features.argocd.active` | `false` | Boolean | Installs ArgoCD as GitOps CD tool | +| `--argocd-operator` | `features.argocd.operator` | `false` | Boolean | Install ArgoCD operator | +| `--argocd-url` | `features.argocd.url` | `''` | String | The url of your external argocd | +| `--argocd-email-from` | `features.argocd.emailFrom` | `'argocd@example.org'` | String | Email from address for ArgoCD notifications | +| `--argocd-email-to-user` | `features.argocd.emailToUser` | `'app-team@example.org'` | String | Email to address for user notifications | +| `--argocd-email-to-admin` | `features.argocd.emailToAdmin` | `'infra@example.org'` | String | Email to address for admin notifications | +| `--argocd-resource-inclusions-cluster` | `features.argocd.resourceInclusionsCluster` | `''` | String | ArgoCD resource inclusions for cluster | +| `--argocd-namespace` | `features.argocd.namespace` | `'argocd'` | String | ArgoCD namespace | +| - | `features.argocd.env` | - | List | Environment variables for ArgoCD | + +###### Mail + +| CLI | Config | Default | Type | Description | +|-----|--------|---------|------|-------------| +| `--mailhog, --mail` | `features.mail.mailhog` | `false` | Boolean | Installs Mailhog as email testing tool | +| `--mailhog-url` | `features.mail.mailhogUrl` | `''` | String | The url of your external mailhog | +| `--smtp-address` | `features.mail.smtpAddress` | `''` | String | SMTP server address | +| `--smtp-port` | `features.mail.smtpPort` | `null` | Integer | SMTP server port | +| `--smtp-user` | `features.mail.smtpUser` | `''` | String | SMTP username | +| `--smtp-password` | `features.mail.smtpPassword` | `''` | String | SMTP password | +| `--mailhog-image` | `features.mail.helm.image` | `'ghcr.io/cloudogu/mailhog:v1.0.1'` | String | Mailhog container image | +| - | `features.mail.helm.chart` | `'mailhog'` | String | Name of the Helm chart | +| - | `features.mail.helm.repoURL` | `'https://codecentric.github.io/helm-charts'` | String | Repository url from which the Helm chart should be obtained | +| - | `features.mail.helm.version` | `'5.0.1'` | String | The version of the Helm chart to be installed | +| - | `features.mail.helm.values` | `[:]` | Map | Helm values of the chart | + +###### Monitoring + +| CLI | Config | Default | Type | Description | +|-----|--------|---------|------|-------------| +| `--metrics, --monitoring` | `features.monitoring.active` | `false` | Boolean | Installs monitoring stack (Prometheus, Grafana) | +| `--grafana-url` | `features.monitoring.grafanaUrl` | `''` | String | The url of your external grafana | +| `--grafana-email-from` | `features.monitoring.grafanaEmailFrom` | `'grafana@example.org'` | String | Email from address for Grafana notifications | +| `--grafana-email-to` | `features.monitoring.grafanaEmailTo` | `'infra@example.org'` | String | Email to address for Grafana notifications | +| `--grafana-image` | `features.monitoring.helm.grafanaImage` | `''` | String | Grafana container image | +| `--grafana-sidecar-image` | `features.monitoring.helm.grafanaSidecarImage` | `''` | String | Grafana sidecar container image | +| `--prometheus-image` | `features.monitoring.helm.prometheusImage` | `''` | String | Prometheus container image | +| `--prometheus-operator-image` | `features.monitoring.helm.prometheusOperatorImage` | `''` | String | Prometheus operator container image | +| `--prometheus-config-reloader-image` | `features.monitoring.helm.prometheusConfigReloaderImage` | `''` | String | Prometheus config reloader container image | +| - | `features.monitoring.helm.chart` | `'kube-prometheus-stack'` | String | Name of the Helm chart | +| - | `features.monitoring.helm.repoURL` | `'https://prometheus-community.github.io/helm-charts'` | String | Repository url from which the Helm chart should be obtained | +| - | `features.monitoring.helm.version` | `'69.7.4'` | String | The version of the Helm chart to be installed | +| - | `features.monitoring.helm.values` | `[:]` | Map | Helm values of the chart | + +###### Secrets + +| CLI | Config | Default | Type | Description | +|-----|--------|---------|------|-------------| +| `--vault` | `features.secrets.vault.mode` | - | VaultMode | Install Vault for secrets management | +| `--vault-url` | `features.secrets.vault.url` | `''` | String | The url of your external vault | +| `--vault-image` | `features.secrets.vault.helm.image` | `''` | String | Vault container image | +| `--external-secrets-image` | `features.secrets.externalSecrets.helm.image` | `''` | String | External secrets operator image | +| `--external-secrets-certcontroller-image` | `features.secrets.externalSecrets.helm.certControllerImage` | `''` | String | External secrets cert controller image | +| `--external-secrets-webhook-image` | `features.secrets.externalSecrets.helm.webhookImage` | `''` | String | External secrets webhook image | +| - | `features.secrets.vault.helm.chart` | `'vault'` | String | Name of the Helm chart | +| - | `features.secrets.vault.helm.repoURL` | `'https://helm.releases.hashicorp.com'` | String | Repository url from which the Helm chart should be obtained | +| - | `features.secrets.vault.helm.version` | `'0.25.0'` | String | The version of the Helm chart to be installed | +| - | `features.secrets.externalSecrets.helm.chart` | `'external-secrets'` | String | Name of the Helm chart | +| - | `features.secrets.externalSecrets.helm.repoURL` | `'https://charts.external-secrets.io'` | String | Repository url from which the Helm chart should be obtained | +| - | `features.secrets.externalSecrets.helm.version` | `'0.9.16'` | String | The version of the Helm chart to be installed | + +###### Ingress Nginx + +| CLI | Config | Default | Type | Description | +|-----|--------|---------|------|-------------| +| `--ingress-nginx` | `features.ingressNginx.active` | `false` | Boolean | Install Ingress Nginx controller | +| `--ingress-nginx-image` | `features.ingressNginx.helm.image` | `''` | String | Ingress Nginx controller image | +| - | `features.ingressNginx.helm.chart` | `'ingress-nginx'` | String | Name of the Helm chart | +| - | `features.ingressNginx.helm.repoURL` | `'https://kubernetes.github.io/ingress-nginx'` | String | Repository url from which the Helm chart should be obtained | +| - | `features.ingressNginx.helm.version` | `'4.12.1'` | String | The version of the Helm chart to be installed | +| - | `features.ingressNginx.helm.values` | `[:]` | Map | Helm values of the chart | + +###### Cert Manager + +| CLI | Config | Default | Type | Description | +|-----|--------|---------|------|-------------| +| `--cert-manager` | `features.certManager.active` | `false` | Boolean | Install cert-manager for TLS certificate management | +| `--cert-manager-image` | `features.certManager.helm.image` | `''` | String | Cert-manager controller image | +| `--cert-manager-webhook-image` | `features.certManager.helm.webhookImage` | `''` | String | Cert-manager webhook image | +| `--cert-manager-cainjector-image` | `features.certManager.helm.cainjectorImage` | `''` | String | Cert-manager CA injector image | +| `--cert-manager-acme-solver-image` | `features.certManager.helm.acmeSolverImage` | `''` | String | Cert-manager ACME solver image | +| `--cert-manager-startup-api-check-image` | `features.certManager.helm.startupAPICheckImage` | `''` | String | Cert-manager startup API check image | +| - | `features.certManager.helm.chart` | `'cert-manager'` | String | Name of the Helm chart | +| - | `features.certManager.helm.repoURL` | `'https://charts.jetstack.io'` | String | Repository url from which the Helm chart should be obtained | +| - | `features.certManager.helm.version` | `'1.16.1'` | String | The version of the Helm chart to be installed | +| - | `features.certManager.helm.values` | `[:]` | Map | Helm values of the chart | + +###### Content + +| CLI | Config | Default | Type | Description | +|-----|--------|---------|------|-------------| +| `--content-examples` | `content.examples` | `false` | Boolean | Deploy example content: source repos, GitOps repos, Jenkins Job, Argo CD apps/project | +| - | `content.namespaces` | `[]` | List | Additional kubernetes namespaces | +| - | `content.repos` | `[]` | List | Content repos to push into target environment | +| - | `content.variables` | `[:]` | Map | Additional variables to use in custom templates | +| - | `content.repos[].url` | `''` | String | URL of the content repo. Mandatory for each type | +| - | `content.repos[].path` | `'.'` | String | Path within the content repo to process | +| - | `content.repos[].ref` | `''` | String | Reference for a specific branch, tag, or commit | +| - | `content.repos[].targetRef` | `''` | String | Reference for a specific branch or tag in the target repo | +| - | `content.repos[].username` | `''` | String | Username to authenticate against content repo | +| - | `content.repos[].password` | `''` | String | Password to authenticate against content repo | +| - | `content.repos[].templating` | `false` | Boolean | When true, template all files ending in .ftl within the repo | +| - | `content.repos[].type` | `MIRROR` | ContentRepoType | Content repo type (FOLDER_BASED, COPY, MIRROR) | +| - | `content.repos[].target` | `''` | String | Target repo for the repository in the form of namespace/name | +| - | `content.repos[].overwriteMode` | `INIT` | OverwriteMode | How customer repos will be updated (INIT, RESET, UPGRADE) | +| - | `content.repos[].createJenkinsJob` | `false` | Boolean | If true, creates a Jenkins job | ##### Configuration file @@ -318,6 +565,15 @@ In addition, you might want to delete the config-map as well. kubectl delete cm gitops-config ``` + +##### Print all CLI parameters + +You can get a full list of all CLI options like so: + +```shell +docker run -t --rm ghcr.io/cloudogu/gitops-playground --help +``` + ##### Deploy Ingress Controller In the default installation the GitOps-Playground comes without an Ingress-Controller. @@ -831,7 +1087,7 @@ We fall back to using imperative helm installation as a kind of neutral ground. ### Jenkins You can set an external jenkins server via the following parameters when applying the playground. -See [parameters](#additional-parameters) for examples. +See [parameters](#overview-of-all-cli-and-config-options) for examples. * `--jenkins-url`, * `--jenkins-username`, @@ -851,7 +1107,7 @@ a docker host. That is, Jenkins must be able to run e.g. `docker ps` successfull ### SCM-Manager You can set an external SCM-Manager via the following parameters when applying the playground. -See [Parameters](#additional-parameters) for examples. +See [parameters](#overview-of-all-cli-and-config-options) for examples. * `--scmm-url`, * `--scmm-username`,