From ad11c7a136cd4684aabf89442ce24a02efcbe870 Mon Sep 17 00:00:00 2001 From: Tobias Brunner Date: Tue, 21 Jul 2020 18:05:20 +0200 Subject: [PATCH 1/3] restructure docs and add deletion info --- Makefile | 3 + docs/modules/ROOT/pages/explanation.adoc | 84 ----------- .../ROOT/pages/explanation/deletion.adoc | 34 +++++ .../ROOT/pages/explanation/design.adoc | 62 ++++++++ .../ROOT/pages/how-tos/create-cluster.adoc | 38 +++++ .../ROOT/pages/how-tos/create-gitrepo.adoc | 30 ++++ .../ROOT/pages/how-tos/create-tenant.adoc | 28 ++++ .../ROOT/pages/how-tos/gitlab-connection.adoc | 30 ++++ .../ROOT/pages/how-tos/installation.adoc | 16 ++ docs/modules/ROOT/pages/how-tos/vault.adoc | 16 ++ docs/modules/ROOT/pages/howtos.adoc | 140 ------------------ docs/modules/ROOT/pages/index.adoc | 8 +- docs/modules/ROOT/pages/install.adoc | 19 --- .../ROOT/pages/references/configuration.adoc | 36 +++-- .../ROOT/pages/references/crds-html.adoc | 3 + .../ROOT/partials/nav-explanation.adoc | 3 +- docs/modules/ROOT/partials/nav-howtos.adoc | 7 +- 17 files changed, 297 insertions(+), 260 deletions(-) delete mode 100644 docs/modules/ROOT/pages/explanation.adoc create mode 100644 docs/modules/ROOT/pages/explanation/deletion.adoc create mode 100644 docs/modules/ROOT/pages/explanation/design.adoc create mode 100644 docs/modules/ROOT/pages/how-tos/create-cluster.adoc create mode 100644 docs/modules/ROOT/pages/how-tos/create-gitrepo.adoc create mode 100644 docs/modules/ROOT/pages/how-tos/create-tenant.adoc create mode 100644 docs/modules/ROOT/pages/how-tos/gitlab-connection.adoc create mode 100644 docs/modules/ROOT/pages/how-tos/installation.adoc create mode 100644 docs/modules/ROOT/pages/how-tos/vault.adoc delete mode 100644 docs/modules/ROOT/pages/howtos.adoc delete mode 100644 docs/modules/ROOT/pages/install.adoc diff --git a/Makefile b/Makefile index 0faf168d..95a984ef 100644 --- a/Makefile +++ b/Makefile @@ -60,6 +60,9 @@ docker: .PHONY: docs docs: generate $(web_dir)/index.html +.PHONY: docs-html +docs-html: $(web_dir)/index.html + $(web_dir)/index.html: playbook.yml $(pages) $(antora_cmd) $(antora_opts) $< diff --git a/docs/modules/ROOT/pages/explanation.adoc b/docs/modules/ROOT/pages/explanation.adoc deleted file mode 100644 index 94508f58..00000000 --- a/docs/modules/ROOT/pages/explanation.adoc +++ /dev/null @@ -1,84 +0,0 @@ -= Explanations - -== What does the operator do exactly? - -The main interaction point with the operator is through the API. The operator's job is to keep inventory about all the clusters and tenants that are managed using SYN. It will also bootstrap the Vault secrets and Git repositories necessary for SYN to work correctly. - -== Operator Common - -The first iteration is a single Operator consisting of several -controllers, sharing CR Go structs as the objects depend on each other. -A later iteration could split these controllers into their own Operator -if it makes sense then. The Operator will be implemented using the -https://github.com/operator-framework/operator-sdk/[operator-sdk] in Go. - -== Handled CRDs - -The CRds that the operator is handling are currently living in these groups and versions. - -[cols=",",options="header",] -|=== -a| -Property - -a| -Value - -|API group |`syn.tools` -|API version |`v1alpha1` -|=== - -[cols=",",options="header",] -|=== - -a| -CRD - -a| -Description - -|_Tenant_ |When a tenant is created, a _GitRepo_ object -is created to create the *tenant configuration repository*. - -|_GitRepo_ a| -Git repository management (CRUD repositories on GitLab, GitHub and Gitea). -Lieutenant manages the CR objects and queries the status fields to get -the status. - -The Operator manages the following objects: - -_GitRepo_ - -* Create Git repository + -** By default on http://git.vshn.net/[git.vshn.net] GitLab -** Supported are GitLab, GitHub and Gitea APIs -** SSH key delivered by Steward is configured as deploy key -* Delete Git repository -* Update Git repository when configuration changes -** Only SSH deploy key change supported - -|_Cluster_ a| -When a _Cluster_ object is created: - -* a _GitRepo_ object is created to create the *cluster catalog -configuration repository*. -* a _Proxy_ object is created to provision an Inlets endpoint for the -cluster - -When a _Cluster_ object is deleted: - -* All created objects are deleted by ownerReference mechanisms - -|_Proxy_ a| -Manages the deployment and configuration of an Inlets server per Syn -Kubernetes cluster. - -Details tbd - -|=== - - -== References - -* Operator SDK - -https://github.com/operator-framework/operator-sdk/[https://github.com/operator-framework/operator-sdk] diff --git a/docs/modules/ROOT/pages/explanation/deletion.adoc b/docs/modules/ROOT/pages/explanation/deletion.adoc new file mode 100644 index 00000000..cf882986 --- /dev/null +++ b/docs/modules/ROOT/pages/explanation/deletion.adoc @@ -0,0 +1,34 @@ += Object Deletion + +Object deletion is considered a dangerous activity which could lead into dataloss, therefore Lieutenant Operator implements a safeguard and a configuration per object what to do with external resources. + +== Deletion Protection + +The annotation `syn.tools/protected-delete` controls if an object can be deleted or not. As long as this annotation holds the value `true`, the finalizer will block the object from being deleted. + +Objects generated by the Operator (mainly the `GitRepo` object) are annotated as configured in the environment variable `LIEUTENANT_DELETE_PROTECTION` (see xref:references/configuration.adoc[References/Configuration]). + +== Deletion Policy + +The deletion policy defines how external resources (for example Git repositories, Vault secrets) are handled when an object gets deleted. + +[cols=",,",options="header",] +|=== + +|Policy +|Git repo +|Vault secret + +|_Archive_ +|Archival of Git repository +|Secret soft deletion + +|_Delete_ +|Deletion of Git repository +|Secret hard deletion + +|_Retain_ +|Do nothing +|Do nothing + +|=== diff --git a/docs/modules/ROOT/pages/explanation/design.adoc b/docs/modules/ROOT/pages/explanation/design.adoc new file mode 100644 index 00000000..e100686c --- /dev/null +++ b/docs/modules/ROOT/pages/explanation/design.adoc @@ -0,0 +1,62 @@ += Operator Design + +== API Group and Version + +The CRDs that the operator is handling are living in these groups and versions: + +[cols=",",options="header",] +|=== +a| +Property + +a| +Value + +|API group |`syn.tools` +|API version |`v1alpha1` +|=== + +The API documentation of these CRDs can be found under xref:references/crds-html.adoc[References/CRDs]. + +== CRD Description + +A high-level description about the idea behind the objects: + +[cols=",",options="header",] +|=== + +|CRD +|Description + +|_Tenant_ +a|When a tenant is created, a _GitRepo_ object +is created to create the *tenant configuration repository*. + +|_GitRepo_ +a|Git repository management (CRUD repositories on GitLab, GitHub and Gitea). +Lieutenant manages the CR objects and queries the status fields to get +the status. + +The Operator manages the following objects: + +_GitRepo_ + +* Create Git repository + +** By default on http://git.vshn.net/[git.vshn.net] GitLab +** Supported are GitLab, GitHub and Gitea APIs +** SSH key delivered by Steward is configured as deploy key +* Delete Git repository +* Update Git repository when configuration changes +** Only SSH deploy key change supported + +|_Cluster_ +a|When a _Cluster_ object is created: + +* a _GitRepo_ object is created to create the *cluster catalog +configuration repository*. + +When a _Cluster_ object is deleted: + +* All created objects are deleted by `ownerReference` mechanisms + +|=== diff --git a/docs/modules/ROOT/pages/how-tos/create-cluster.adoc b/docs/modules/ROOT/pages/how-tos/create-cluster.adoc new file mode 100644 index 00000000..0b7e01e1 --- /dev/null +++ b/docs/modules/ROOT/pages/how-tos/create-cluster.adoc @@ -0,0 +1,38 @@ += Create a Cluster + +The following example manifest will create a cluster: + +[source,yaml] +.... +apiVersion: syn.tools/v1alpha1 +kind: Cluster +metadata: + name: c-ae3os1 + namespace: lieutenant + annotations: + syn.tools/protected-delete: "false" +spec: + displayName: Another Big Corp. Production Cluster + deletionPolicy: Delete + gitRepoTemplate: + path: cluster + repoName: cluster2 + deletionPolicy: Delete + apiSecretRef: + name: lieutenant-secret + namespace: lieutenant + deployKeys: + test: + type: ssh-ed25519 + key: AAAACxxxx + writeAccess: true + tenantRef: + name: t-aezoo6 + tokenLifeTime: 4h + facts: + distribution: openshift3 + cloud: cloudscale + region: rma1 +.... + +Please be aware that you first need to have a valid secret containing the endpoint information, see xref:how-tos/gitlab-connection.adoc[Connection to GitLab]. diff --git a/docs/modules/ROOT/pages/how-tos/create-gitrepo.adoc b/docs/modules/ROOT/pages/how-tos/create-gitrepo.adoc new file mode 100644 index 00000000..702a61a2 --- /dev/null +++ b/docs/modules/ROOT/pages/how-tos/create-gitrepo.adoc @@ -0,0 +1,30 @@ += Create a Git Repository + +It's usually not necessary to create a Git Repository manually, as they're automatically created through a cluster or tenant. But if you need an operator managed git repository you can do that with the following manifest. + +The following example manifest will create a Git Repository: + +[source,yaml] +.... +apiVersion: syn.tools/v1alpha1 +kind: GitRepo +metadata: + name: example-gitrepo2 + namespace: lieutenant +spec: + tenantRef: + name: foo + namespace: lieutenant + apiSecretRef: + name: lieutenant-secret + path: cluster/subgroup + repoName: bar + deployKeys: + test: + type: ssh-ed25519 + key: AAAACxxxx + writeAccess: true + writeAccess: false +.... + +Please be aware that you first need to have a valid secret containing the endpoint information, see xref:how-tos/gitlab-connection.adoc[Connection to GitLab]. \ No newline at end of file diff --git a/docs/modules/ROOT/pages/how-tos/create-tenant.adoc b/docs/modules/ROOT/pages/how-tos/create-tenant.adoc new file mode 100644 index 00000000..8a6b984d --- /dev/null +++ b/docs/modules/ROOT/pages/how-tos/create-tenant.adoc @@ -0,0 +1,28 @@ += Create a Tenant + +The following example manifest will create a tenant: + +[source,yaml] +.... +apiVersion: syn.tools/v1alpha1 +kind: Tenant +metadata: + name: t-aezoo6 + namespace: lieutenant +spec: + displayName: Big Corp. + gitRepoTemplate: + path: tenant + repoName: tenant1 + deletionPolicy: Delete + apiSecretRef: + name: lieutenant-secret + namespace: lieutenant + deployKeys: + test: + type: ssh-ed25519 + key: AAAACxxxx + writeAccess: true +.... + +Please be aware that you first need to have a valid secret containing the endpoint information, see xref:how-tos/gitlab-connection.adoc[Connection to GitLab]. \ No newline at end of file diff --git a/docs/modules/ROOT/pages/how-tos/gitlab-connection.adoc b/docs/modules/ROOT/pages/how-tos/gitlab-connection.adoc new file mode 100644 index 00000000..ea751ff4 --- /dev/null +++ b/docs/modules/ROOT/pages/how-tos/gitlab-connection.adoc @@ -0,0 +1,30 @@ += Connection to GitLab + +For the Lieutenant Operator to be able to connect to the GitLab API, the following configuration needs to be made. + +== Get GitLab Token + +Visit the GitLab instance you'd like to use. Login with the user that has the permissions necessary to write to the group you want to store your Project Syn repositories. + +Visit `\https://yourgitlab/profile/personal_access_tokens` and create a token with the following settings: + +image::gitlab_settings.png[] + +== Add Secret with Endpoint Information + +Before any other things can be created we need to specify the git endpoints first. + +[source,yaml] +.... +apiVersion: v1 +stringData: + endpoint: http://10.144.1.197:8080 + token: Bvi1s19qp25Wt-rtGfMy +kind: Secret +metadata: + name: lieutenant-secret + namespace: syn-lieutenant +type: Opaque +.... + +Save the file as `secret.yaml` and then apply it with `kubectl apply -f secret.yaml`. diff --git a/docs/modules/ROOT/pages/how-tos/installation.adoc b/docs/modules/ROOT/pages/how-tos/installation.adoc new file mode 100644 index 00000000..d7d9b63f --- /dev/null +++ b/docs/modules/ROOT/pages/how-tos/installation.adoc @@ -0,0 +1,16 @@ += Installation of the Operator + +The Operator provides a Kustomize folder which allows for easy installation: + +[source,shell] +-- +kubectl create namespace lieutenant + +# CRDs (global scope) +kubectl apply -k github.com/projectsyn/lieutenant-operator/deploy/crds + +# Operator deployment +kubectl -n lieutenant apply -k github.com/projectsyn/lieutenant-operator/deploy +-- + +The deployment artefact are to be found in the https://github.com/projectsyn/lieutenant-operator/tree/master/deploy[`/deploy`] folder. \ No newline at end of file diff --git a/docs/modules/ROOT/pages/how-tos/vault.adoc b/docs/modules/ROOT/pages/how-tos/vault.adoc new file mode 100644 index 00000000..d06f7e83 --- /dev/null +++ b/docs/modules/ROOT/pages/how-tos/vault.adoc @@ -0,0 +1,16 @@ += Vault Configuration + +To configure Vault so that Lieutenant Operator can use it, follow these steps: + +. Visit `\https://yourvault/ui/vault/policies/acl` and click `Create ACL Policy`. Then paste following policy into the field: ++ +[source,hcl] +---- +include::partial$policy.hcl[] +---- ++ +Name it `lieutenant-operator` +. Create a new secret engine by visiting `\https://yourvault/ui/vault/secrets` and clicking on `Enable new engine`. +.. Select KV +.. Click next, the path needs to be `kv` and the `Version` needs to be 2 +.. Click `Enable Engine` \ No newline at end of file diff --git a/docs/modules/ROOT/pages/howtos.adoc b/docs/modules/ROOT/pages/howtos.adoc deleted file mode 100644 index 17fdf602..00000000 --- a/docs/modules/ROOT/pages/howtos.adoc +++ /dev/null @@ -1,140 +0,0 @@ -= How-to Guides - -== Configure Vault - -Visit https://yourvault/ui/vault/policies/acl and click `Create ACL Policy`. Then paste following Policy into the field: - -[source,hcl] ----- -include::partial$policy.hcl[] ----- - -Name it `lieutenant-operator`. - -Then create a new secret engine. Visit https://yourvault/ui/vault/secrets and click `Enable new engine`. Select KV and click next. The path needs to be `kv` and the `Version` needs to be 2. Click `Enable Engine`. - -== Get GitLab Token - -Visit the GitLab instance you'd like to use. Login with the user that has the permissions necessary to write to the group you want to store your SYN repositories. - -Visit https://yourgitlab/profile/personal_access_tokens and create a token with the following settings: - -image::gitlab_settings.png[] - -== Add Secret with Endpoint Information - -Before any other things can be created we need to specify the git endpoints first. - -[source,yaml] -.... -apiVersion: v1 -stringData: - endpoint: http://10.144.1.197:8080 - token: Bvi1s19qp25Wt-rtGfMy -kind: Secret -metadata: - name: lieutenant-secret - namespace: syn-lieutenant -type: Opaque -.... - -To create a token please see <>. Save the file as `secret.yaml` and then apply it with `kubectl apply -f secret.yaml`. - -== Create a Tenant - -Following manifest will create a tenant: - -[source,yaml] -.... -apiVersion: syn.tools/v1alpha1 -kind: Tenant -metadata: - name: t-aezoo6 - namespace: syn-lieutenant -spec: - displayName: Big Corp. - gitRepoTemplate: - path: tenant - repoName: tenant1 - deletionPolicy: Delete - apiSecretRef: - name: lieutenant-secret - namespace: syn-lieutenant - deployKeys: - test: - type: ssh-ed25519 - key: AAAACxxxx - writeAccess: true -.... - -Please be aware that you first need to have a valid secret containing the endpoint information. See <>. - -== Create a Cluster - -Following manifest will create a cluster: - -[source,yaml] -.... -apiVersion: syn.tools/v1alpha1 -kind: Cluster -metadata: - name: c-ae3os1 - namespace: syn-lieutenant - annotations: - syn.tools/protected-delete: "false" -spec: - displayName: Another Big Corp. Production Cluster - deletionPolicy: Delete - gitRepoTemplate: - path: cluster - repoName: cluster2 - deletionPolicy: Delete - apiSecretRef: - name: lieutenant-secret - namespace: syn-lieutenant - deployKeys: - test: - type: ssh-ed25519 - key: AAAACxxxx - writeAccess: true - tenantRef: - name: t-aezoo6 - tokenLifeTime: 4h - facts: - distribution: openshift3 - cloud: cloudscale - region: rma1 -.... - -Please be aware that you first need to have a valid secret containing the endpoint information. See <>. - -== Create a Git Repository - -It's usually not necessary to create a Git Repository manually, as they're automatically created through a cluster or tenant. But if you need an operator managed git repository you can do that with the following manifest. - -Following manifest will create a Git Repository: - -[source,yaml] -.... -apiVersion: syn.tools/v1alpha1 -kind: GitRepo -metadata: - name: example-gitrepo2 - namespace: syn-lieutenant -spec: - tenantRef: - name: foo - namespace: syn-lieutenant - apiSecretRef: - name: lieutenant-secret - path: cluster/subgroup - repoName: bar - deployKeys: - test: - type: ssh-ed25519 - key: AAAACxxxx - writeAccess: true - writeAccess: false -.... - -Please be aware that you first need to have a valid secret containing the endpoint information. See <>. diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index 42a810b8..c4ee8ce3 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -1,4 +1,4 @@ -= Project SYN: Lieutenant Operator += Lieutenant Operator Welcome to the documentation of the Lieutenant Operator - a Project Syn tool. @@ -7,3 +7,9 @@ image::syn.png[] Keeping inventory about tenants and clusters. It's the "database" for the link:https://github.com/projectsyn/lieutenant-api[lieutenant-api]. It primarily holds information about the tenants and clusters. It also handles the management of some requirements like Git repositories and secret management: it can automatically populate Git repositories with skeleton files when a new cluster is added. It will also generate a token to be used by link:https://github.com/projectsyn/steward[Steward]. + +The main interaction point with the Lieutenant Operator is through the https://syn.tools/lieutenant-api/[Lieutenant API]. + +The operator is written in Go using the https://github.com/operator-framework/operator-sdk/[Operator SDK]. + +TIP: To get started fast, have a look at the tutorial https://syn.tools/syn/getting-started.html[Getting Started with Project Syn]. \ No newline at end of file diff --git a/docs/modules/ROOT/pages/install.adoc b/docs/modules/ROOT/pages/install.adoc deleted file mode 100644 index 3d5453cf..00000000 --- a/docs/modules/ROOT/pages/install.adoc +++ /dev/null @@ -1,19 +0,0 @@ -= Tutorials - -== Install Operator -[source,shell] --- -kubectl create ns syn-lieutenant -kubectl -n syn-lieutenant apply -k deploy/crds/ -kubectl -n syn-lieutenant apply -k deploy/ --- - -Check that the operator is running. - -[source,shell] --- -kubectl get -n syn-lieutenant pods - -NAME READY STATUS RESTARTS AGE -lieutenant-operator-85fc5c986b-vn2h7 1/1 Running 0 8s --- diff --git a/docs/modules/ROOT/pages/references/configuration.adoc b/docs/modules/ROOT/pages/references/configuration.adoc index 903fcfaa..c803b7ae 100644 --- a/docs/modules/ROOT/pages/references/configuration.adoc +++ b/docs/modules/ROOT/pages/references/configuration.adoc @@ -1,26 +1,36 @@ = Configuration -This section is the configuration reference for the operator. +Lieutenant Operator is configured via environment variables: -== Environment variables - -[cols=",",options="header",] +[cols=",,",options="header",] |=== -a| Environment Variable - -a| Description +|Environment Variable +|Description +|Default -| VAULT_ADDR | Sets the address to the Vault instance +|VAULT_ADDR +|Sets the address to the Vault instance +| -| VAULT_TOKEN | Sets the Vault token to be used, only recommended for testing. In production the https://www.vaultproject.io/docs/auth/kubernetes[K8s authentication] should be used by omitting the setting. +|VAULT_TOKEN +|Sets the Vault token to be used, only recommended for testing. In production the https://www.vaultproject.io/docs/auth/kubernetes[K8s authentication] should be used by omitting the setting. +| -| SKIP_VAULT_SETUP | Doesn't create any Vault secrets. Recommended for testing only. +|SKIP_VAULT_SETUP +|Doesn't create any Vault secrets. Recommended for testing only. +|false -| DEFAULT_DELETION_POLICY | Sets what deletion policy for external resources (Git, Vault) should be used by default. One of `Archive`, `Delete`, `Retain` +|DEFAULT_DELETION_POLICY +|Sets what deletion policy for external resources (Git, Vault) should be used by default. One of `Archive`, `Delete`, `Retain`. See xref:explanation/deletion.adoc[Explanation/Object Deletion] for more information. +|Archive -| LIEUTENANT_SYNC_DURATION | Defines with what frequency the CRs will be synced. Default: 5m +|LIEUTENANT_DELETE_PROTECTION +|Defines whether the annotation to protect for accidental deletion should be set by default. See xref:explanation/deletion.adoc[Explanation/Object Deletion] for more information. +|true -| LIEUTENANT_DELETE_PROTECTION | Defines whether the annotation to protect for accidental deletion should be set by default. Default: true +|LIEUTENANT_SYNC_DURATION +|Defines with what frequency the CRs will be synced +|5m |=== diff --git a/docs/modules/ROOT/pages/references/crds-html.adoc b/docs/modules/ROOT/pages/references/crds-html.adoc index 9000d41d..a18a927c 100644 --- a/docs/modules/ROOT/pages/references/crds-html.adoc +++ b/docs/modules/ROOT/pages/references/crds-html.adoc @@ -1,3 +1,6 @@ += CRD Documentation +:notitle: + ++++ include::partial$crds.html[] ++++ diff --git a/docs/modules/ROOT/partials/nav-explanation.adoc b/docs/modules/ROOT/partials/nav-explanation.adoc index 40e89339..8078a6e6 100644 --- a/docs/modules/ROOT/partials/nav-explanation.adoc +++ b/docs/modules/ROOT/partials/nav-explanation.adoc @@ -1 +1,2 @@ -* xref:lieutenant-operator:ROOT:explanation.adoc[Various] +* xref:lieutenant-operator:ROOT:explanation/design.adoc[Operator Design] +* xref:lieutenant-operator:ROOT:explanation/deletion.adoc[Object Deletion] diff --git a/docs/modules/ROOT/partials/nav-howtos.adoc b/docs/modules/ROOT/partials/nav-howtos.adoc index fcb85cf2..7c3ab369 100644 --- a/docs/modules/ROOT/partials/nav-howtos.adoc +++ b/docs/modules/ROOT/partials/nav-howtos.adoc @@ -1,2 +1,5 @@ -* xref:lieutenant-operator:ROOT:install.adoc[Installation] -* xref:lieutenant-operator:ROOT:howtos.adoc[How Tos] +* xref:lieutenant-operator:ROOT:how-tos/installation.adoc[Installation] +* xref:lieutenant-operator:ROOT:how-tos/vault.adoc[Vault Configuration] +* xref:lieutenant-operator:ROOT:how-tos/create-tenant.adoc[Create a Tenant] +* xref:lieutenant-operator:ROOT:how-tos/create-cluster.adoc[Create a Cluster] +* xref:lieutenant-operator:ROOT:how-tos/create-gitrepo.adoc[Create a Git Repository] From 0f3fa77a93b200be60ab4dd2f998cd48046a5e39 Mon Sep 17 00:00:00 2001 From: Tobias Brunner Date: Wed, 22 Jul 2020 11:07:27 +0200 Subject: [PATCH 2/3] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Simon Rüegg --- docs/modules/ROOT/pages/explanation/deletion.adoc | 6 +++--- docs/modules/ROOT/pages/how-tos/create-cluster.adoc | 6 +++--- docs/modules/ROOT/pages/how-tos/create-gitrepo.adoc | 4 +--- 3 files changed, 7 insertions(+), 9 deletions(-) diff --git a/docs/modules/ROOT/pages/explanation/deletion.adoc b/docs/modules/ROOT/pages/explanation/deletion.adoc index cf882986..3a4ffc9c 100644 --- a/docs/modules/ROOT/pages/explanation/deletion.adoc +++ b/docs/modules/ROOT/pages/explanation/deletion.adoc @@ -6,7 +6,7 @@ Object deletion is considered a dangerous activity which could lead into datalos The annotation `syn.tools/protected-delete` controls if an object can be deleted or not. As long as this annotation holds the value `true`, the finalizer will block the object from being deleted. -Objects generated by the Operator (mainly the `GitRepo` object) are annotated as configured in the environment variable `LIEUTENANT_DELETE_PROTECTION` (see xref:references/configuration.adoc[References/Configuration]). +The Operator automatically annotates objects as configured in the environment variable `LIEUTENANT_DELETE_PROTECTION` (see xref:references/configuration.adoc[References/Configuration]). == Deletion Policy @@ -21,11 +21,11 @@ The deletion policy defines how external resources (for example Git repositories |_Archive_ |Archival of Git repository -|Secret soft deletion +|Secret https://www.vaultproject.io/docs/secrets/kv/kv-v2#deleting-and-destroying-data[soft deletion] |_Delete_ |Deletion of Git repository -|Secret hard deletion +|Secret https://www.vaultproject.io/docs/secrets/kv/kv-v2#deleting-and-destroying-data[hard deletion] |_Retain_ |Do nothing diff --git a/docs/modules/ROOT/pages/how-tos/create-cluster.adoc b/docs/modules/ROOT/pages/how-tos/create-cluster.adoc index 0b7e01e1..3a101599 100644 --- a/docs/modules/ROOT/pages/how-tos/create-cluster.adoc +++ b/docs/modules/ROOT/pages/how-tos/create-cluster.adoc @@ -15,10 +15,10 @@ spec: displayName: Another Big Corp. Production Cluster deletionPolicy: Delete gitRepoTemplate: - path: cluster - repoName: cluster2 + path: cluster-catalogs # path (org/group) to repo + repoName: cluster2 # name of the repo to create deletionPolicy: Delete - apiSecretRef: + apiSecretRef: # reference to a secret containing credentials for the git provider name: lieutenant-secret namespace: lieutenant deployKeys: diff --git a/docs/modules/ROOT/pages/how-tos/create-gitrepo.adoc b/docs/modules/ROOT/pages/how-tos/create-gitrepo.adoc index 702a61a2..91ba12ee 100644 --- a/docs/modules/ROOT/pages/how-tos/create-gitrepo.adoc +++ b/docs/modules/ROOT/pages/how-tos/create-gitrepo.adoc @@ -14,7 +14,6 @@ metadata: spec: tenantRef: name: foo - namespace: lieutenant apiSecretRef: name: lieutenant-secret path: cluster/subgroup @@ -24,7 +23,6 @@ spec: type: ssh-ed25519 key: AAAACxxxx writeAccess: true - writeAccess: false .... -Please be aware that you first need to have a valid secret containing the endpoint information, see xref:how-tos/gitlab-connection.adoc[Connection to GitLab]. \ No newline at end of file +Please be aware that you first need to have a valid secret containing the endpoint information, see xref:how-tos/gitlab-connection.adoc[Connection to GitLab]. From 6e6776b6182fefde7171d4bb000eebcdab2f8abe Mon Sep 17 00:00:00 2001 From: Tobias Brunner Date: Wed, 22 Jul 2020 11:13:24 +0200 Subject: [PATCH 3/3] update with suggestions from review --- .../ROOT/pages/explanation/design.adoc | 2 +- .../ROOT/pages/how-tos/create-tenant.adoc | 5 ---- .../ROOT/pages/how-tos/gitlab-connection.adoc | 26 +++++++------------ docs/modules/ROOT/partials/nav-howtos.adoc | 1 + 4 files changed, 11 insertions(+), 23 deletions(-) diff --git a/docs/modules/ROOT/pages/explanation/design.adoc b/docs/modules/ROOT/pages/explanation/design.adoc index e100686c..397ac5da 100644 --- a/docs/modules/ROOT/pages/explanation/design.adoc +++ b/docs/modules/ROOT/pages/explanation/design.adoc @@ -43,7 +43,7 @@ _GitRepo_ * Create Git repository + ** By default on http://git.vshn.net/[git.vshn.net] GitLab -** Supported are GitLab, GitHub and Gitea APIs +** Supported is GitLab. Support for GitHub and Gitea is planned. ** SSH key delivered by Steward is configured as deploy key * Delete Git repository * Update Git repository when configuration changes diff --git a/docs/modules/ROOT/pages/how-tos/create-tenant.adoc b/docs/modules/ROOT/pages/how-tos/create-tenant.adoc index 8a6b984d..abf17df7 100644 --- a/docs/modules/ROOT/pages/how-tos/create-tenant.adoc +++ b/docs/modules/ROOT/pages/how-tos/create-tenant.adoc @@ -18,11 +18,6 @@ spec: apiSecretRef: name: lieutenant-secret namespace: lieutenant - deployKeys: - test: - type: ssh-ed25519 - key: AAAACxxxx - writeAccess: true .... Please be aware that you first need to have a valid secret containing the endpoint information, see xref:how-tos/gitlab-connection.adoc[Connection to GitLab]. \ No newline at end of file diff --git a/docs/modules/ROOT/pages/how-tos/gitlab-connection.adoc b/docs/modules/ROOT/pages/how-tos/gitlab-connection.adoc index ea751ff4..ee1b1d78 100644 --- a/docs/modules/ROOT/pages/how-tos/gitlab-connection.adoc +++ b/docs/modules/ROOT/pages/how-tos/gitlab-connection.adoc @@ -4,27 +4,19 @@ For the Lieutenant Operator to be able to connect to the GitLab API, the followi == Get GitLab Token -Visit the GitLab instance you'd like to use. Login with the user that has the permissions necessary to write to the group you want to store your Project Syn repositories. - -Visit `\https://yourgitlab/profile/personal_access_tokens` and create a token with the following settings: - +. Visit the GitLab instance you'd like to use. +. Login with the user that has the permissions necessary to write to the group you want to store your Project Syn repositories. +. Visit `\https://yourgitlab/profile/personal_access_tokens` and create a token with the following settings: ++ image::gitlab_settings.png[] == Add Secret with Endpoint Information -Before any other things can be created we need to specify the git endpoints first. +Before any other things can be created we need to specify the Git repository API endpoint first: -[source,yaml] +[source,shell] .... -apiVersion: v1 -stringData: - endpoint: http://10.144.1.197:8080 - token: Bvi1s19qp25Wt-rtGfMy -kind: Secret -metadata: - name: lieutenant-secret - namespace: syn-lieutenant -type: Opaque +kubectl -n lieutenant create secret generic lieutenant-secret \ + --from-literal endpoint=http://10.144.1.197:8080 \ + --from-literal token= .... - -Save the file as `secret.yaml` and then apply it with `kubectl apply -f secret.yaml`. diff --git a/docs/modules/ROOT/partials/nav-howtos.adoc b/docs/modules/ROOT/partials/nav-howtos.adoc index 7c3ab369..8ce0ab45 100644 --- a/docs/modules/ROOT/partials/nav-howtos.adoc +++ b/docs/modules/ROOT/partials/nav-howtos.adoc @@ -1,5 +1,6 @@ * xref:lieutenant-operator:ROOT:how-tos/installation.adoc[Installation] * xref:lieutenant-operator:ROOT:how-tos/vault.adoc[Vault Configuration] +* xref:lieutenant-operator:ROOT:how-tos/gitlab-connection.adoc[GitLab Connection] * xref:lieutenant-operator:ROOT:how-tos/create-tenant.adoc[Create a Tenant] * xref:lieutenant-operator:ROOT:how-tos/create-cluster.adoc[Create a Cluster] * xref:lieutenant-operator:ROOT:how-tos/create-gitrepo.adoc[Create a Git Repository]