From c5fbe9957d387c0ce7a00d8c6b77eda8918cf797 Mon Sep 17 00:00:00 2001 From: Andrew Rynhard Date: Sun, 4 Nov 2018 13:44:54 -0800 Subject: [PATCH] docs: improve configuration documentation (#186) --- docs/categories/index.html | 11 +- docs/components/blockd/index.html | 13 +- docs/components/index.html | 11 +- docs/components/index.xml | 2 +- docs/components/init/index.html | 11 +- docs/components/kernel/index.html | 11 +- docs/components/kubeadm/index.html | 11 +- docs/components/osctl/index.html | 11 +- docs/components/osd/index.html | 13 +- docs/components/proxyd/index.html | 11 +- docs/components/trustd/index.html | 11 +- docs/configuration/index.html | 20 +- docs/configuration/index.xml | 25 +- .../{controlplane => masters}/index.html | 166 ++++++-- docs/configuration/osd/index.html | 381 ++++++++++++++++++ docs/configuration/workers/index.html | 55 ++- docs/css/main.css | 11 +- docs/dianemo/index.html | 11 +- docs/examples/aws/index.html | 11 +- docs/examples/index.html | 11 +- docs/examples/kvm/index.html | 11 +- docs/index.html | 11 +- docs/index.json | 2 +- docs/index.xml | 55 ++- docs/sitemap.xml | 27 +- docs/tags/index.html | 11 +- src/docs/src/content/components/blockd.md | 3 +- src/docs/src/content/components/osd.md | 2 +- src/docs/src/content/configuration/_index.md | 7 +- .../src/content/configuration/controlplane.md | 55 --- src/docs/src/content/configuration/masters.md | 136 +++++++ src/docs/src/content/configuration/osd.md | 111 +++++ src/docs/src/content/configuration/workers.md | 39 +- .../autonomy/layouts/shortcodes/note.html | 3 + .../src/themes/autonomy/static/css/main.css | 11 +- 35 files changed, 1085 insertions(+), 206 deletions(-) rename docs/configuration/{controlplane => masters}/index.html (68%) create mode 100644 docs/configuration/osd/index.html delete mode 100644 src/docs/src/content/configuration/controlplane.md create mode 100644 src/docs/src/content/configuration/masters.md create mode 100644 src/docs/src/content/configuration/osd.md create mode 100644 src/docs/src/themes/autonomy/layouts/shortcodes/note.html diff --git a/docs/categories/index.html b/docs/categories/index.html index 6ab8e0e11..7c823cc3f 100644 --- a/docs/categories/index.html +++ b/docs/categories/index.html @@ -191,8 +191,15 @@
  • - Control Plane + href="https://dianemo.autonomy.io/configuration/osd/" > + osd + +
    • + +
  • + + Masters
    • diff --git a/docs/components/blockd/index.html b/docs/components/blockd/index.html index de2ece515..29ae9216d 100644 --- a/docs/components/blockd/index.html +++ b/docs/components/blockd/index.html @@ -191,8 +191,15 @@
  • - Control Plane + href="https://dianemo.autonomy.io/configuration/osd/" > + osd + +
    • + +
  • + + Masters
    • @@ -260,7 +267,7 @@

    These partitions are reserved and cannot be modified. -The one expection to this is that the DATA partition will be resized automatically in the init process to the maximum size possible. +The one exception to this is that the DATA partition will be resized automatically in the init process to the maximum size possible. Managing any other block device can be done via the blockd service.

    diff --git a/docs/components/index.html b/docs/components/index.html index 834ec5b0c..994f131dc 100644 --- a/docs/components/index.html +++ b/docs/components/index.html @@ -191,8 +191,15 @@
  • - Control Plane + href="https://dianemo.autonomy.io/configuration/osd/" > + osd + +
    • + +
  • + + Masters
    • diff --git a/docs/components/index.xml b/docs/components/index.xml index 9b16371fd..0f0e2433d 100644 --- a/docs/components/index.xml +++ b/docs/components/index.xml @@ -86,7 +86,7 @@ To make this work, we needed an out-of-band tool for managing the nodes. In an i https://dianemo.autonomy.io/components/blockd/ Dianemo comes with a reserved block device with three partitions: - an EFI System Partition (ESP) a ROOT partition mounted as read-only that contains the minimal set of binaries to operate system services and a DATA partion that is mounted as read/write at /var/run These partitions are reserved and cannot be modified. The one expection to this is that the DATA partition will be resized automatically in the init process to the maximum size possible. + an EFI System Partition (ESP) a ROOT partition mounted as read-only that contains the minimal set of binaries to operate system services and a DATA partion that is mounted as read/write at /var/run These partitions are reserved and cannot be modified. The one exception to this is that the DATA partition will be resized automatically in the init process to the maximum size possible. diff --git a/docs/components/init/index.html b/docs/components/init/index.html index e3c2ecf71..2fcfefff4 100644 --- a/docs/components/init/index.html +++ b/docs/components/init/index.html @@ -191,8 +191,15 @@
  • - Control Plane + href="https://dianemo.autonomy.io/configuration/osd/" > + osd + +
    • + +
  • + + Masters
    • diff --git a/docs/components/kernel/index.html b/docs/components/kernel/index.html index 127a495fc..7d0065f42 100644 --- a/docs/components/kernel/index.html +++ b/docs/components/kernel/index.html @@ -191,8 +191,15 @@
  • - Control Plane + href="https://dianemo.autonomy.io/configuration/osd/" > + osd + +
    • + +
  • + + Masters
    • diff --git a/docs/components/kubeadm/index.html b/docs/components/kubeadm/index.html index 52a70107f..9e140e4fe 100644 --- a/docs/components/kubeadm/index.html +++ b/docs/components/kubeadm/index.html @@ -191,8 +191,15 @@
  • - Control Plane + href="https://dianemo.autonomy.io/configuration/osd/" > + osd + +
    • + +
  • + + Masters
    • diff --git a/docs/components/osctl/index.html b/docs/components/osctl/index.html index a0f7d3e3b..d8a92647e 100644 --- a/docs/components/osctl/index.html +++ b/docs/components/osctl/index.html @@ -191,8 +191,15 @@
  • - Control Plane + href="https://dianemo.autonomy.io/configuration/osd/" > + osd + +
    • + +
  • + + Masters
    • diff --git a/docs/components/osd/index.html b/docs/components/osd/index.html index 99c551262..88fe2362b 100644 --- a/docs/components/osd/index.html +++ b/docs/components/osd/index.html @@ -191,8 +191,15 @@
  • - Control Plane + href="https://dianemo.autonomy.io/configuration/osd/" > + osd + +
    • + +
  • + + Masters
    • @@ -263,7 +270,7 @@ But, in the real world, this does not happen. We still need a way to handle operational scenarios that may arise.

    The osd daemon provides a way to do just that. -Based on the Principle of Least Privilege, osd provides operational value for cluster administrations by providing an API for node management.

    +Based on the Principle of Least Privilege, osd provides operational value for cluster administrators by providing an API for node management.

    diff --git a/docs/components/proxyd/index.html b/docs/components/proxyd/index.html index cd588628f..7c00a766b 100644 --- a/docs/components/proxyd/index.html +++ b/docs/components/proxyd/index.html @@ -191,8 +191,15 @@
  • - Control Plane + href="https://dianemo.autonomy.io/configuration/osd/" > + osd + +
    • + +
  • + + Masters
    • diff --git a/docs/components/trustd/index.html b/docs/components/trustd/index.html index 9acaf02be..421afeb65 100644 --- a/docs/components/trustd/index.html +++ b/docs/components/trustd/index.html @@ -191,8 +191,15 @@
  • - Control Plane + href="https://dianemo.autonomy.io/configuration/osd/" > + osd + +
    • + +
  • + + Masters
    • diff --git a/docs/configuration/index.html b/docs/configuration/index.html index 320f59f8f..2a313af98 100644 --- a/docs/configuration/index.html +++ b/docs/configuration/index.html @@ -191,8 +191,15 @@
  • - Control Plane + href="https://dianemo.autonomy.io/configuration/osd/" > + osd + +
    • + +
  • + + Masters
    • @@ -245,7 +252,14 @@

    Configuration

    -

    In this section we will discuss the configuration of a Dianemo node.

    +

    In this section, we will step through the configuration of a Dianemo based Kubernetes cluster. +There are three major components we will configure:

    + +
      +
    • osd and osctl
      • +
    • the master nodes
      • +
    • the worker nodes
      • +

    diff --git a/docs/configuration/index.xml b/docs/configuration/index.xml index 9d0a7bec8..64d530362 100644 --- a/docs/configuration/index.xml +++ b/docs/configuration/index.xml @@ -12,12 +12,25 @@ - Control Plane - https://dianemo.autonomy.io/configuration/controlplane/ + osd + https://dianemo.autonomy.io/configuration/osd/ + Sat, 03 Nov 2018 17:14:49 -0700 + + https://dianemo.autonomy.io/configuration/osd/ + The osd service enforces a high level of security by utilizing mutual TLS for authentication and authorization. In this section we will configure mutual TLS by generating the certificates for the servers (osd) and clients (osctl). +Cluster Owners We recommend that the configuration of osd be performed by a cluster owner. A cluster owner should be a person of authority within an organization. Perhaps a director, manager, or senior member of a team. + + + + Masters + https://dianemo.autonomy.io/configuration/masters/ Mon, 29 Oct 2018 19:40:55 -0700 - https://dianemo.autonomy.io/configuration/controlplane/ - version: "" security: os: ca: crt: ${BASE64_ENCODED_PEM_FORMATTED_PUBLIC_X509} key: ${BASE64_ENCODED_PEM_FORMATTED_PRIVATE_X509} identity: crt: ${BASE64_ENCODED_PEM_FORMATTED_PUBLIC_X509} key: ${BASE64_ENCODED_PEM_FORMATTED_PRIVATE_X509} kubernetes: ca: crt: ${BASE64_ENCODED_PEM_FORMATTED_PUBLIC_X509} key: ${BASE64_ENCODED_PEM_FORMATTED_PRIVATE_X509} networking: os: {} kubernetes: {} services: kubeadm: init: type: initial etcdMemberName: etcd-1 containerRuntime: docker configuration: | apiVersion: kubeadm.k8s.io/v1alpha2 kind: MasterConfiguration clusterName: example bootstrapTokens: - token: abcdef.0123456789abcdef ttl: 0s kubeProxy: config: ipvs: scheduler: lc mode: ipvs networking: dnsDomain: cluster.local podSubnet: 10.244.0.0/16 serviceSubnet: 10.96.0.0/12 trustd: username: example password: example You can generate the PKI resources and inject them into the configuration with osctl. + https://dianemo.autonomy.io/configuration/masters/ + Configuring master nodes in a Dianemo Kubernetes cluster is a two part process: + configuring the Dianemo specific options and configuring the Kubernetes specific options To get started, create a YAML file we will use in the following steps: +touch <node-name>.yaml Configuring Dianemo Injecting the Dianemo PKI Using osctl, and our output from the PKI instructions, inject the generated PKI into the configuration file: +osctl inject os --crt <organization>. @@ -26,7 +39,9 @@ Mon, 29 Oct 2018 19:40:55 -0700 https://dianemo.autonomy.io/configuration/workers/ - version: "" security: os: ca: crt: ${BASE64_ENCODED_PEM_FORMATTED_PUBLIC_X509} networking: os: {} kubernetes: {} services: kubeadm: containerRuntime: docker configuration: | apiVersion: kubeadm.k8s.io/v1alpha2 kind: NodeConfiguration token: abcdef.0123456789abcdef discoveryTokenAPIServers: - ${MASTER_IP}:443 discoveryTokenCACertHashes: - sha256:${CA_CERT_HASH} trustd: username: example password: example endpoints: - ${MASTER_IP} + Configuring the worker nodes is much more simple in comparison to configuring the master nodes. Using the trustd API, worker nodes submit a CSR, and, if authenticated, receive a valid osd certificate. Similarly, using a kubeadm token, the node joins an existing cluster. +We need to specify: + the osd public certificate trustd credentials and endpoints and a kubeadm JoinConfiguration version: "" security: os: ca: crt: <base 64 encoded root public certificate> services: kubeadm: configuration: | apiVersion: kubeadm. diff --git a/docs/configuration/controlplane/index.html b/docs/configuration/masters/index.html similarity index 68% rename from docs/configuration/controlplane/index.html rename to docs/configuration/masters/index.html index 3b701da9a..6e1166324 100644 --- a/docs/configuration/controlplane/index.html +++ b/docs/configuration/masters/index.html @@ -189,10 +189,17 @@