Merge pull request #87 from projectsyn/finetune_docs

Restructure docs and add deletion info

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) $<
 

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.
+
+The Operator automatically annotates objects 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 https://www.vaultproject.io/docs/secrets/kv/kv-v2#deleting-and-destroying-data[soft deletion]
+
+|_Delete_
+|Deletion of Git repository
+|Secret https://www.vaultproject.io/docs/secrets/kv/kv-v2#deleting-and-destroying-data[hard deletion]
+
+|_Retain_
+|Do nothing
+|Do nothing
+
+|===

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 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
+** 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
+
+|===

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-catalogs # path (org/group) to repo
+    repoName: cluster2 # name of the repo to create
+    deletionPolicy: Delete
+    apiSecretRef: # reference to a secret containing credentials for the git provider
+      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].

docs/modules/ROOT/pages/how-tos/create-gitrepo.adoc

@@ -0,0 +1,28 @@
+= 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
+  apiSecretRef:
+    name: lieutenant-secret
+  path: cluster/subgroup
+  repoName: bar
+  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].

docs/modules/ROOT/pages/how-tos/create-tenant.adoc

@@ -0,0 +1,23 @@
+= 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
+....
+
+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].

docs/modules/ROOT/pages/how-tos/gitlab-connection.adoc

@@ -0,0 +1,22 @@
+= 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 repository API endpoint first:
+
+[source,shell]
+....
+kubectl -n lieutenant create secret generic lieutenant-secret \
+  --from-literal endpoint=http://10.144.1.197:8080 \
+  --from-literal token=<token>
+....

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.

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`