diff --git a/docs/modules/ROOT/pages/how-tos/openstack/install.adoc b/docs/modules/ROOT/pages/how-tos/openstack/install.adoc new file mode 100644 index 00000000..6df1dc60 --- /dev/null +++ b/docs/modules/ROOT/pages/how-tos/openstack/install.adoc @@ -0,0 +1,296 @@ += Install OpenShift 4 on OpenStack +:ocp-minor-version: 4.13 +:k8s-minor-version: 1.26 +:ocp-patch-version: {ocp-minor-version}.0 +:provider: openstack + +[abstract] +-- +Steps to install an OpenShift 4 cluster on Red Hat OpenStack. + +These steps follow the https://docs.openshift.com/container-platform/4.13/installing/installing_openstack/installing-openstack-installer-custom.html[Installing a cluster on OpenStack] docs to set up an installer provisioned installation (IPI). +-- + +[IMPORTANT] +-- +This how-to guide is an early draft. +So far, we've setup only one cluster using the instructions in this guide. +-- + +[NOTE] +-- +The certificates created during bootstrap are only valid for 24h. +So make sure you complete these steps within 24h. +-- + +== Starting situation + +* You already have a Project Syn Tenant and its Git repository +* You have a CCSP Red Hat login and are logged into https://console.redhat.com/openshift/install/openstack/installer-provisioned[Red Hat Openshift Cluster Manager] ++ +IMPORTANT: Don't use your personal account to login to the cluster manager for installation. +* You want to register a new cluster in Lieutenant and are about to install Openshift 4 on OpenStack + +== Prerequisites + +include::partial$/install/prerequisites.adoc[] +* `unzip` +* `openstack` CLI ++ +[TIP] +==== +The OpenStack CLI is available as a Python package. + +.Ubuntu/Debian +[source,bash] +---- +sudo apt install python3-openstackclient +---- + +.Arch +[source,bash] +---- +sudo yay -S python-openstackclient +---- + +.MacOS +[source,bash] +---- +brew install openstackclient +---- + +Optionally, you can also install additional CLIs for object storage (`swift`) and images (`glance`). +==== + +== Cluster Installation + +include::partial$install/register.adoc[] + +=== Configure input + +.OpenStack API +[source,bash] +---- +export OS_AUTH_URL= <1> +---- +<1> Provide the URL with the leading `https://` + +.OpenStack credentials +[source,bash] +---- +export OS_USERNAME= +export OS_PASSWORD= +---- + +.OpenStack project, region and domain details +[source,bash] +---- +export OS_PROJECT_NAME= +export OS_PROJECT_DOMAIN_NAME= +export OS_USER_DOMAIN_NAME= +export OS_REGION_NAME= +export OS_PROJECT_ID=$(openstack project show $OS_PROJECT_NAME -f json | jq -r .id) <1> +---- +<1> TBD if really needed + +.Cluster machine network +[source,bash] +---- +export MACHINE_NETWORK_CIDR= +export EXTERNAL_NETWORK_NAME= <1> +---- +<1> The instructions create floating IPs for the API and ingress in the specified network. + +.VM flavors +[source,bash] +---- +export CONTROL_PLANE_FLAVOR= <1> +export INFRA_FLAVOR= <1> +export APP_FLAVOR= <1> +---- +<1> Check `openstack flavor list` for available options. + +include::partial$install/vshn-input.adoc[] + +[#_set_vault_secrets] +=== Set secrets in Vault + +include::partial$connect-to-vault.adoc[] + +.Store various secrets in Vault +[source,bash] +---- +# Store OpenStack credentials +vault kv put clusters/kv/${TENANT_ID}/${CLUSTER_ID}/openstack/credentials \ + username=${OS_USERNAME} \ + password=${OS_PASSWORD} + +# Generate an HTTP secret for the registry +vault kv put clusters/kv/${TENANT_ID}/${CLUSTER_ID}/registry \ + httpSecret=$(LC_ALL=C tr -cd "A-Za-z0-9" \ + --from-literal=REGISTRY_STORAGE_S3_SECRETKEY= +---- ++ +include::partial$install/registry-samples-operator.adoc[] + +include::partial$install/finalize_part1.adoc[] + +include::partial$install/finalize_part2.adoc[] diff --git a/docs/modules/ROOT/pages/how-tos/vsphere/install.adoc b/docs/modules/ROOT/pages/how-tos/vsphere/install.adoc index 0a67b71e..e4998880 100644 --- a/docs/modules/ROOT/pages/how-tos/vsphere/install.adoc +++ b/docs/modules/ROOT/pages/how-tos/vsphere/install.adoc @@ -129,22 +129,7 @@ include::partial$install/prepare-syn-config.adoc[] === Provision the cluster -[NOTE] -==== -The steps in this section must be run on a host which can reach the vSphere API. -If you can't reach the vSphere API directly, you can setup a SOCKS5 proxy with the following commands: - -[source,bash] ----- -export JUMPHOST_FQDN= <1> -ssh -D 12000 -q -f -N ${JUMPHOST_FQDN} <2> -export https_proxy=socks5://localhost:12000 <3> -export CURL_OPTS="-xsocks5h://localhost:12000" ----- -<1> The FQDN or SSH alias of the host which can reach the vSphere API -<2> This command expects that your SSH config is setup so that `ssh ${JUMPHOST_FQDN}` works without further configuration -<3> The `openshift-install` tool respects the `https_proxy` environment variable -==== +include::partial$install/socks5-proxy.adoc[] . Trust the vSphere CA certificate + diff --git a/docs/modules/ROOT/partials/install/configure-installer.adoc b/docs/modules/ROOT/partials/install/configure-installer.adoc index 5b6abeac..df8cac9f 100644 --- a/docs/modules/ROOT/partials/install/configure-installer.adoc +++ b/docs/modules/ROOT/partials/install/configure-installer.adoc @@ -25,17 +25,12 @@ ssh-add $SSH_PRIVATE_KEY . Prepare `install-config.yaml` + -[NOTE] -==== -You can add more options to the `install-config.yaml` file. -Have a look at the https://docs.openshift.com/container-platform/{ocp-minor-version}/installing/installing_bare_metal/installing-bare-metal.html#installation-bare-metal-config-yaml_installing-bare-metal[config example] for more information. - -For example, you could change the SDN from a default value to something a customer requests due to some network requirements. -==== -+ ifeval::["{provider}" == "vsphere"] include::partial$install/install-config-vsphere.adoc[] endif::[] +ifeval::["{provider}" == "openstack"] +include::partial$install/install-config-openstack.adoc[] +endif::[] ifeval::["{provider}" == "cloudscale"] include::partial$install/install-config-cloudscale-exoscale.adoc[] endif::[] diff --git a/docs/modules/ROOT/partials/install/finalize_part1.adoc b/docs/modules/ROOT/partials/install/finalize_part1.adoc index 46cd53ea..cf95fa14 100644 --- a/docs/modules/ROOT/partials/install/finalize_part1.adoc +++ b/docs/modules/ROOT/partials/install/finalize_part1.adoc @@ -1,3 +1,10 @@ +ifeval::["{provider}" == "cloudscale"] +:acme-dns-update-zone: yes +endif::[] +ifeval::["{provider}" == "openstack"] +:acme-dns-update-zone: yes +endif::[] + :dummy: ifeval::["{provider}" == "vsphere"] === Set default storage class @@ -32,7 +39,7 @@ fulldomain=$(kubectl -n syn-cert-manager \ echo "$fulldomain" ---- -ifeval::["{provider}" == "cloudscale"] +ifeval::["{acme-dns-update-zone}" == "yes"] . Add the following CNAME records to the cluster's DNS zone + [IMPORTANT] diff --git a/docs/modules/ROOT/partials/install/install-config-cloudscale-exoscale.adoc b/docs/modules/ROOT/partials/install/install-config-cloudscale-exoscale.adoc index 32baa44f..43a3e865 100644 --- a/docs/modules/ROOT/partials/install/install-config-cloudscale-exoscale.adoc +++ b/docs/modules/ROOT/partials/install/install-config-cloudscale-exoscale.adoc @@ -1,3 +1,11 @@ +[NOTE] +==== +You can add more options to the `install-config.yaml` file. +Have a look at the https://docs.openshift.com/container-platform/{ocp-minor-version}/installing/installing_bare_metal/installing-bare-metal.html#installation-bare-metal-config-yaml_installing-bare-metal[config example] for more information. + +For example, you could change the SDN from a default value to something a customer requests due to some network requirements. +==== ++ [source,bash] ---- export INSTALLER_DIR="$(pwd)/target" diff --git a/docs/modules/ROOT/partials/install/install-config-openstack.adoc b/docs/modules/ROOT/partials/install/install-config-openstack.adoc new file mode 100644 index 00000000..2d94f40e --- /dev/null +++ b/docs/modules/ROOT/partials/install/install-config-openstack.adoc @@ -0,0 +1,75 @@ +[NOTE] +==== +You can add more options to the `install-config.yaml` file. +Have a look at the https://docs.openshift.com/container-platform/4.13/installing/installing_openstack/installing-openstack-installer-custom.html#installation-configuration-parameters_installing-openstack-installer-custom[installation configuration parameters] for more information. +==== ++ +[source,bash] +---- +export INSTALLER_DIR="$(pwd)/target" +mkdir -p "${INSTALLER_DIR}" + +cat > "${INSTALLER_DIR}/clouds.yaml" < "${INSTALLER_DIR}/install-config.yaml" < + - architecture: amd64 + hyperthreading: Enabled + name: worker + replicas: 3 + platform: + openstack: + type: ${APP_FLAVOR} + rootVolume: + size: 100 + type: __DEFAULT__ # TODO: is this generally applicable? + additionalSecurityGroupIDs: <2> + - ${CILIUM_SECURITY_GROUP_ID} +controlPlane: + architecture: amd64 + hyperthreading: Enabled + name: master + replicas: 3 + platform: + openstack: + type: ${CONTROL_PLANE_FLAVOR} + rootVolume: + size: 100 + type: __DEFAULT__ # TODO: is this generally applicable? + additionalSecurityGroupIDs: <2> + - ${CILIUM_SECURITY_GROUP_ID} +platform: + openstack: + cloud: shiftstack <3> + externalNetwork: ${EXTERNAL_NETWORK_NAME} + apiFloatingIP: ${API_VIP} + ingressFloatingIP: ${INGRESS_VIP} +networking: + networkType: Cilium + machineNetwork: + - cidr: ${MACHINE_NETWORK_CIDR} +pullSecret: | + ${PULL_SECRET} +sshKey: "$(cat $SSH_PUBLIC_KEY)" +EOF +---- +<1> We only provision a single compute machine set. +The final machine sets will be configured through Project Syn. +<2> We attach the Cilium security group to both the control plane and the worker nodes. +This ensures that there's no issues with Cilium traffic during bootstrapping. +<3> This field must match the entry in `clouds` in the `clouds.yaml` file. +If you're following this guide, you shouldn't need to adjust this. diff --git a/docs/modules/ROOT/partials/install/install-config-vsphere.adoc b/docs/modules/ROOT/partials/install/install-config-vsphere.adoc index 4025a2b6..f39dfc13 100644 --- a/docs/modules/ROOT/partials/install/install-config-vsphere.adoc +++ b/docs/modules/ROOT/partials/install/install-config-vsphere.adoc @@ -1,3 +1,9 @@ +[NOTE] +==== +You can add more options to the `install-config.yaml` file. +Have a look at the https://docs.openshift.com/container-platform/4.13/installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.html#installation-configuration-parameters_installing-vsphere-installer-provisioned-customizations[installation configuration parameters] for more information. +==== ++ [source,bash] ---- export INSTALLER_DIR="$(pwd)/target" diff --git a/docs/modules/ROOT/partials/install/prepare-syn-config-openstack.adoc b/docs/modules/ROOT/partials/install/prepare-syn-config-openstack.adoc new file mode 100644 index 00000000..4e8277b9 --- /dev/null +++ b/docs/modules/ROOT/partials/install/prepare-syn-config-openstack.adoc @@ -0,0 +1,10 @@ +. Configure OpenStack parameters ++ +[source,bash] +---- +yq eval -i ".parameters.openshift.openstack.app_flavor = \"${APP_FLAVOR}\"" \ + ${CLUSTER_ID}.yml + +yq eval -i ".parameters.openshift.openstack.infra_flavor = \"${INFRA_FLAVOR}\"" \ + ${CLUSTER_ID}.yml +---- diff --git a/docs/modules/ROOT/partials/install/prepare-syn-config.adoc b/docs/modules/ROOT/partials/install/prepare-syn-config.adoc index e65c0e51..a78ae5b3 100644 --- a/docs/modules/ROOT/partials/install/prepare-syn-config.adoc +++ b/docs/modules/ROOT/partials/install/prepare-syn-config.adoc @@ -59,15 +59,24 @@ yq eval -i ".parameters.openshift4_version.spec.channel = \"fast-{ocp-minor-vers ---- ==== +ifeval::["{provider}" == "cloudscale"] +:is-terraform: yes +endif::[] +ifeval::["{provider}" == "exoscale"] +:is-terraform: yes +endif::[] -ifeval::["{provider}" != "vsphere"] +ifeval::["{is-terraform}" == "yes"] include::partial$install/prepare-syn-config-terraform.adoc[] endif::[] ifeval::["{provider}" == "vsphere"] include::partial$install/prepare-syn-config-vsphere.adoc[] endif::[] +ifeval::["{provider}" == "openstack"] +include::partial$install/prepare-syn-config-openstack.adoc[] +endif::[] -ifeval::["{provider}" != "vsphere"] +ifeval::["{is-terraform}" == "yes"] [TIP] ==== You now have the option to further customize the cluster by editing `terraform_variables`. diff --git a/docs/modules/ROOT/partials/install/socks5-proxy.adoc b/docs/modules/ROOT/partials/install/socks5-proxy.adoc new file mode 100644 index 00000000..e5ce0a32 --- /dev/null +++ b/docs/modules/ROOT/partials/install/socks5-proxy.adoc @@ -0,0 +1,24 @@ +:provider-display: UNKNOWN +ifeval::["{provider}" == "vsphere"] +:provider-display: vSphere +endif::[] +ifeval::["{provider}" == "openstack"] +:provider-display: OpenStack +endif::[] + +[NOTE] +==== +The steps in this section must be run on a host which can reach the {provider-display} API. +If you can't reach the {provider-display} API directly, but a SSH jumphost is available, you can setup a SOCKS5 proxy with the following commands: + +[source,bash] +---- +export JUMPHOST_FQDN= <1> +ssh -D 12000 -q -f -N ${JUMPHOST_FQDN} <2> +export https_proxy=socks5://localhost:12000 <3> +export CURL_OPTS="-xsocks5h://localhost:12000" +---- +<1> The FQDN or SSH alias of the host which can reach the {provider-display} API +<2> This command expects that your SSH config is setup so that `ssh ${JUMPHOST_FQDN}` works without further configuration +<3> The `openshift-install` tool respects the `https_proxy` environment variable +==== diff --git a/docs/modules/ROOT/partials/install/vshn-input.adoc b/docs/modules/ROOT/partials/install/vshn-input.adoc index d8fe90bc..3dbd0b2d 100644 --- a/docs/modules/ROOT/partials/install/vshn-input.adoc +++ b/docs/modules/ROOT/partials/install/vshn-input.adoc @@ -1,5 +1,10 @@ -ifeval::["{provider}" != "vsphere"] -:needs_hieradata_edit: yes +ifeval::["{provider}" == "vsphere"] +:needs_hieradata_edit: no +:needs_gitlab: no +endif::[] +ifeval::["{provider}" == "openstack"] +:needs_hieradata_edit: no +:needs_gitlab: no endif::[] include::partial$vshn-input.adoc[] diff --git a/docs/modules/ROOT/partials/nav.adoc b/docs/modules/ROOT/partials/nav.adoc index 25578297..03cf0b54 100644 --- a/docs/modules/ROOT/partials/nav.adoc +++ b/docs/modules/ROOT/partials/nav.adoc @@ -58,6 +58,9 @@ *** xref:oc4:ROOT:how-tos/vsphere/change-vsphere-creds.adoc[vSphere Credentials] *** xref:oc4:ROOT:how-tos/vsphere/change-vsphere-params.adoc[vSphere Parameters] +** OpenStack +*** xref:oc4:ROOT:how-tos/openstack/install.adoc[Install] + ** Google Cloud Platform *** xref:oc4:ROOT:how-tos/gcp/project.adoc[Project Setup] *** xref:oc4:ROOT:how-tos/gcp/install.adoc[Install] @@ -82,6 +85,9 @@ ** vSphere *** xref:oc4:ROOT:how-tos/vsphere/install.adoc[Install] +** OpenStack +*** xref:oc4:ROOT:how-tos/openstack/install.adoc[Install] + * Update ** xref:oc4:ROOT:how-tos/update_maintenance/automated-upgrades-at-vshn.adoc[] ** xref:oc4:ROOT:how-tos/new_minor.adoc[Get ready for new minor] diff --git a/docs/modules/ROOT/partials/vshn-input.adoc b/docs/modules/ROOT/partials/vshn-input.adoc index 6425ad13..efac3f9e 100644 --- a/docs/modules/ROOT/partials/vshn-input.adoc +++ b/docs/modules/ROOT/partials/vshn-input.adoc @@ -1,4 +1,4 @@ -ifeval::["{provider}" != "vsphere"] +ifeval::["{needs_gitlab}" != "no"] .Access to VSHN GitLab [source,bash] ---- @@ -20,7 +20,7 @@ export CLUSTER_ID= # Looks like: c- export TENANT_ID=$(curl -sH "Authorization: Bearer $(commodore fetch-token)" ${COMMODORE_API_URL}/clusters/${CLUSTER_ID} | jq -r .tenant) ---- -ifeval::["{needs_hieradata_edit}" == "yes"] +ifeval::["{needs_hieradata_edit}" != "no"] .Configuration for hieradata commits [source,bash] ----