Update Required Configuration

kubernetes-sigs · Jul 3, 2020 · d3b9d92 · d3b9d92
1 parent 2e7ed44
commit d3b9d92
Showing 1 changed file with 55 additions and 35 deletions.
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -2,72 +2,68 @@
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 **Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
 
-- [Required Configuration](#required-configuration)
-  - [Cluster configuration YAML files](#cluster-configuration-yaml-files)
-  - [Public Network](#public-network)
-  - [Floating IPs](#floating-ips)
-  - [Operating System Images](#operating-system-images)
+- [Required configuration](#required-configuration)
+  - [Operating system image](#operating-system-image)
+  - [Public network](#public-network)
+  - [Floating IP](#floating-ip)
+  - [SSH authorized key](#ssh-authorized-key)
+  - [OpenStack credential](#openstack-credential)
+  - [Avaialability zone](#avaialability-zone)
+  - [DNS server](#dns-server)
+- [Optional Configuration](#optional-configuration)
   - [Network Filters](#network-filters)
   - [Multiple Networks](#multiple-networks)
   - [Subnet Filters](#subnet-filters)
   - [Tagging](#tagging)
   - [Metadata](#metadata)
-- [Optional Configuration](#optional-configuration)
   - [Boot From Volume](#boot-from-volume)
   - [Timeout settings](#timeout-settings)
   - [Custom pod network CIDR](#custom-pod-network-cidr)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
-# Required Configuration
+# Required configuration
 
-To successfully run a Kubernetes cluster in OpenStack, you will need to configure a few essential properties. The following configurations are necessary:
-  - public network
-  - floating ip address
-  - at least one of the supported operating system images
-  - ssh authorized key
+The cluster configuration file can be generated by using [`clusterctl config cluster`](https://cluster-api.sigs.k8s.io/user/quick-start.html#generating-the-cluster-configuration) command.
+This command actually uses [the template file](../templates/cluster-template.yaml) and replace the values surrounded by `${}` with environment variables. You have to set all required environment variables in advance. The following sections explain some more details about what should be configured.
 
-## Cluster Configuration YAML files
+Note: You can use [the template file](../templates/cluster-template.yaml) by manually replacing values.
 
-The cluster configuration file can be generated by using [`clusterctl config cluster`](https://cluster-api.sigs.k8s.io/user/quick-start.html#generating-the-cluster-configuration) command or by using one of the template files placed under `/template` directory. The file contain configuration on what OpenStack elements to use to create the cluster on, and which cluster components to create. However the template is incomplete and needs to be filled in. The following sections explain some more details about what can be configured.
+## Operating system image
 
-## Public Network
+We currently depend on an update version of cloud-init otherwise the operating system choice is yours. The kubeadm bootstrap provider we're using also depends on some pre-installed software like a controller-runtime, kubelet, kubeadm, etc.. . For an examples how to build such an image take a look at [image-builder (openstack)](https://image-builder.sigs.k8s.io/capi/providers/openstack.html).
+
+The image can be referenced by exposing it as an environment variable `OPENSTACK_IMAGE_NAME`.
+
+## Public network
 
 The public network id can be obtained by using command,
 
 ```bash
-openstack network show <public network name> | grep "\<id\>"
+openstack network list --external
 ```
 The ID must be expose as an environment variable `OPENSTACK_EXTERNAL_NETWORK_ID`
 
 Note: If your openstack cluster does not already have a public network, you should contact your cloud service provider. We will not review how to troubleshoot this here.
 
-## Floating IPs
+## Floating IP
 
-You have to be able to at least assign floating IPs in your OpenStack. If you don't have rights 
-to create floating IPs you have to make sure they already exist before creating the cluster. You can create one using,
+You have to be able to create a floating IP in your OpenStack. You can create one using,
 
 ```bash
 openstack floating ip create <public network>
 ```
 The IP must be exposed as an environment variable `OPENSTACK_CONTROLPLANE_IP`.
 
-## Operating System Images
-
-We currently depend on an update version of cloud-init otherwise the operating system choice is yours. The kubeadm bootstrap provider we're using also depends on some pre-installed software like a controller-runtime, kubelet, kubeadm, etc.. . For an examples how to build such an image take a look at [image-builder (openstack)](https://image-builder.sigs.k8s.io/capi/providers/openstack.html).
+Note: Only user with admin role can create a floating IP with specific IP.
 
-The image can be referenced by exposing it as an environment variable `OPENSTACK_IMAGE_NAME`.
+## SSH authorized key
 
-## SSH Authorized Key
+The ssh public key is required. This key does not need to be created by OpenStack key pair.
 
-Openstack ssh keypair is required for the setup. This can be generated using command,
+The public key must be exposed as an environment variable `OPENSTACK_SSH_AUTHORIZED_KEY`.
 
-```bash
-openstack keypair create <name>
-```
-The keypair must be exposed as an environment variable `OPENSTACK_SSH_AUTHORIZED_KEY`.
-
-If you want to login to each machine by ssh, you have to configure security groups. If `spec.managedSecurityGroups` of `OpenStackCluster` set to true, two security groups will be created. One is `k8s-cluster-${NAMESPACE}-${CLUSTER_NAME}-secgroup-controlplane`, another is `k8s-cluster-${NAMESPACE}-${CLUSTER_NAME}-secgroup-worker`. These security group rules are following kubeadm's [Check required ports](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/install-kubeadm/#check-required-ports) so that each node can not be logged in through ssh by default. Please add existing security group allowing ssh port to `OpenStackMachineTemplate` spec. Here is an example:
+If you want to login to each machine by ssh, you have to configure security groups. If `spec.managedSecurityGroups` of `OpenStackCluster` set to true, two security groups will be created and added to the instances. One is `k8s-cluster-${NAMESPACE}-${CLUSTER_NAME}-secgroup-controlplane`, another is `k8s-cluster-${NAMESPACE}-${CLUSTER_NAME}-secgroup-worker`. These security group rules include the kubeadm's [Check required ports](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/install-kubeadm/#check-required-ports) so that each node can not be logged in through ssh by default. Please add existing security group allowing ssh port to OpenStackMachineTemplate spec. Here is an example:
 
 ```yaml
 apiVersion: infrastructure.cluster.x-k8s.io/v1alpha3
@@ -78,10 +74,36 @@ spec:
   template:
     spec:
       securityGroups:
-      - name: k8s-cluster-${NAMESPACE}-${CLUSTER_NAME}-secgroup-controlplane
       - name: allow-ssh
 ```
 
+## OpenStack credential
+
+The [env.rc](./env.rc) script sets the environment variables related to credentials.
+
+```bash
+source env.rc <path/to/clouds.yaml> <cloud>
+```
+
+The following variables are set.
+
+| Variable | Meaning |
+ :----- | :-------- 
+| OPENSTACK_CLOUD | The cloud name which is used as second argument |
+| OPENSTACK_CLOUD_YAML_B64 | The secret used by Cluster API Provider OpenStack accessing OpenStack |
+| OPENSTACK_CLOUD_PROVIDER_CONF_B64 | The content of [cloud.conf](https://kubernetes.io/docs/concepts/cluster-administration/cloud-providers/#cloud-conf) which is used by OpenStack cloud provider |
+| OPENSTACK_CLOUD_CACERT_B64 | (Optional) The content of your custom CA file which can be specified in your clouds.yaml by `ca-file` |
+
+## Avaialability zone
+
+The availability zone names must be exposed as an environment variable `OPENSTACK_FAILURE_DOMAIN`.
+
+## DNS server
+
+The DNS servers must be exposed as an environment variable `OPENSTACK_DNS_NAMESERVERS`.
+
+# Optional Configuration
+
 ## Network Filters
 
 If you have a complex query that you want to use to lookup a network, then you can do this by using a network filter. More details about the filter can be found in [NetworkParam](../api/v1alpha3/types.go)
@@ -182,8 +204,6 @@ spec:
     nickname: bobbert
 ```
 
-# Optional Configuration
-
 ## Boot From Volume
 
 1. For example in `examples/_out/controlplane.yaml` set `spec.rootVolume.diskSize` to something greater than `0` means boot from volume.
@@ -208,5 +228,5 @@ If creating servers in your OpenStack takes a long time, you can increase the ti
 
 ## Custom pod network CIDR
 
-If `192.168.0.0/16` is already in use within your network, you must select a different pod network CIDR. You have to replace the CIDR `192.168.0.0/16` with your own in the generated example files: `addons.yaml` and `cluster.yaml`.
+If `192.168.0.0/16` is already in use within your network, you must select a different pod network CIDR. You have to replace the CIDR `192.168.0.0/16` with your own in the generated file.