Skip to content

Commit

Permalink
docs: revise docs with latest steps, outputs, and access methods
Browse files Browse the repository at this point in the history 
Signed-off-by: Marques Johansson <[email protected]>
  • Loading branch information
@displague
displague committed Jun 13, 2024
1 parent e142b86 commit 4c98ca1
Show file tree
Hide file tree
Showing 3 changed files with 127 additions and 32 deletions.
18 changes: 4 additions & 14 deletions CLOUDFLARE.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ This deployment automation uses the Cloudflare Managed DNS service.
This domain name (in its "base domain" form) will be used later as a value for the `cluster_basedomain` variable in the Terraform configuration.

```console
Example of the cluster_basedomain value: "domain.com"
Example of the cluster_basedomain value: "example.com"
```

1. Create Cloudflare account
Expand All @@ -32,22 +32,12 @@ This deployment automation uses the Cloudflare Managed DNS service.

1. Copy the API key

On the same page as above click on the “Get your API token” link.
Follow the directions on <https://developers.cloudflare.com/fundamentals/api/get-started/create-token/> to create an API Token for use with this zone.

You will be presented with the “API Token” tab from the “My Profile” page, click the “View” button at the “Global API key”.

Save this key value, it will be used later as value of the `dns_options` `api_key` option in the Terraform configuration.

```console
Example of the cf_api_key parameter value: "65ca543659011ba2a13b2ab06dab12c158bcb"
```

1. Copy email address

On the page above, change to the “Communication” page and save the “Email Address” value, it will be used later as the `dns_options` `email` option in the Terraform configuration.
Save this key value. You will use it in your Terraform environment by defining it as `CLOUDFLARE_API_TOKEN` in the environment.

```console
Example of the cf_email parameter value: "[email protected]"
Example of the cf_api_token parameter value: "65ca543659011ba2a13b2ab06dab12c158bcb"
```

[Top](README.md)
16 changes: 9 additions & 7 deletions EQUINIX.md
View file
Original file line number Diff line number Diff line change
@@ -1,29 +1,31 @@
# Equinix Metal

1. Sign up for a Equinix Metal account at https://console.equinix.com/signup
1. Sign up for a Equinix Metal account at <https://console.equinix.com/signup>

2. Follow the wizard **"Getting Started with Equinix Metal"** at https://console.equinix.com/getting-started/overview that guides you through creating a project.
2. Follow the wizard **"Getting Started with Equinix Metal"** at<https://deploy.equinix.com/developers/docs/metal/getting-started/> that guides you through creating a project.

**IMPORTANT:**

Using the Equinix Metal [web portal](https://console.equinix.com/), upload one or more SSH keys to either your *"Personal Settings"* (personal SSH keys) or the newly created projects' *"Project Settings"* (project-level SSH keys).

These keys will be automatically added (to `.ssh/authorized_keys`) on every server created by you on Equinix Metal. These keys must be generated for every SSH client you will be using to access these servers.

See details at https://metal.equinix.com/developers/docs/servers/key-features/ssh-keys/
See details at <https://deploy.equinix.com/developers/docs/metal/identity-access-management/ssh-keys>

One of these SSH keys must be generated in the host system used for driving the deployment. Copy location and names of these SSH key files on that system, they will be used later as values for `ssh_private_key_path` and `ssh_public_key_path` variables in the Terraform configuration.

3. After the project has been created, navigate to its *"Project Settings"*, and at the *"General"* tab locate the project ID, copy it as is, it will be used later as a value for the `project_id` variable in the Terraform configuration.
3. After the project has been created, navigate to its *"Project Settings"*, and at the *"General"* tab locate the project ID, copy it as is, it will be used later as a value for the `metal_project_id` variable in the Terraform configuration.

```
Example of the project_id value: "e36a901f-d5e1-28e1-0f21-efb1c3676d89"
Example of the metal_project_id value: "e36a901f-d5e1-28e1-0f21-efb1c3676d89"
```

4. Create a single API key, either from either your *"Personal Settings"* or from your project *"Project Settings"*, give it a descriptive name and *"Read/Write"* permissions. Copy this key's token value as is, it will be used later as a value for the `auth_token` variable in the Terraform configuration.
4. Create a single API key, either from either your *"Personal Settings"* or from your project *"Project Settings"*, give it a descriptive name and *"Read/Write"* permissions. Copy this key's token value as is, it will be used later as a value for the `metal_auth_token` variable in the Terraform configuration.

See details at <https://deploy.equinix.com/developers/docs/metal/identity-access-management/api-keys/>

```
Example of the auth_token value: "atBncno1a8ipxEYAKNTpuFp7CyyDDZVA"
Example of the metal_auth_token value: "atBncno1a8ipxEYAKNTpuFp7CyyDDZVA"
```

Next, follow [this](CLOUDFLARE.md)
Expand Down
125 changes: 114 additions & 11 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,22 +28,27 @@ cd terraform-metal-openshift

1. Follow [this](EQUINIX.md) to configure your Equinix Metal project and collect required parameters.

1. Follow [this](CLOUDFLARE.md) to configure your Cloudflare account and collect required parameters.
1. Follow [this](CLOUDFLARE.md) to configure your Cloudflare account and collect required parameters (AWS and Linode DNS options are also available).

1. [Obtain an OpenShift Cluster Manager API Token](https://cloud.redhat.com/openshift/token) for pullSecret generation.

1. Configure TF_VARs applicable to your Equinix Metal project, DNS settings, and OpenShift API Token:

```bash
export TF_VAR_project_id="kajs886-l59-8488-19910kj"
export TF_VAR_auth_token="lka6702KAmVAP8957Abny01051"
export TF_VAR_metal_project_id="fake-uuid-4159-8488-19910kj"
export TF_VAR_metal_auth_token="faketokenAP8957Abny01051"
```

If you have the [Metal CLI](https://deploy.equinix.com/labs/metal-cli) installed, you can use `eval $(metal env --export -o terraform)` to use the token and project configured for use by Metal CLI.

```bash
export TF_VAR_cluster_basedomain="domain.com"
export TF_VAR_ocp_cluster_manager_token="eyJhbGc...d8Agva"
export TF_VAR_dns_provider="cloudflare" # aws and linode are also supported
export TF_VAR_dns_options='{"email": "[email protected]", "api_key": "...", "api_token": "..."}' # fields differ by DNS provider
export TF_VAR_ocp_cluster_manager_token="eyJhbGc...d8Agva" # https://cloud.redhat.com/openshift/token
export TF_VAR_dns_provider="cloudflare" # aws and linode are also offered
```

Alternatively, copy `terraform.tfvars.example` to `terraform.tfvars` and modify the values in that file accordingly.

1. Initialize and validate terraform:

```bash
Expand All @@ -57,22 +62,120 @@ cd terraform-metal-openshift
terraform apply
```

The Terraform output will look like the following after a successful deployment:

```console
Apply complete! Resources: X added, 0 changed, 0 destroyed.
Outputs:
Information = <<EOT
OpenShift cluster deployed.
Access the OpenShift Web Console at: https://console-openshift-console.apps.cluster_name.cluster_base_domain.examples.com
Username: kubeadmin
Password: secret-password
To use the CLI (on bastion):
export KUBECONFIG="/tmp/artifacts/install/auth/kubeconfig"
To use the CLI (locally):
export KUBECONFIG="/Users/username/src/terraform-equinix-metal-openshift-on-baremetal/auth/kubeconfig"
Review your nodes:
oc get nodes
EOT
bastion_ip = "198.51.100.32"
bastion_kubeconfig = "/tmp/artifacts/install/auth/kubeconfig"
console = "https://console-openshift-console.apps.cluster_name.cluster_base_domain.examples.com"
kubeconfig = "/Users/mjohansson/dev/terraform-equinix-metal-openshift-on-baremetal/auth/kubeconfig"
openshift_bootstrap_ip = [
"198.51.100.38",
]
openshift_controlplane_ips = [
[
"198.51.100.70",
"203.0.113.23",
"192.0.2.30",
],
]
openshift_worker_ips = [
[
"198.51.100.12",
"203.0.113.98",
],
]
password = <sensitive>
ssh_private_key_file = "/Users/username/.ssh/id_rsa_mos-mx94n"
ssh_public_key = "ssh-rsa AAAA...=="
username = "kubeadm"
```
To view this output later, use `terraform output`.
1. Cleanup the boostrap node once provisioning and installation is complete by permanently (recommended) or temporarily setting `count_bootstrap=0`
```bash
terraform apply -var="count_bootstrap=0"
export TF_VAR_count_bootstrap=0 # use the terraform.tfvars file to persist this change
terraform apply
```
If you need to obtain your `kubeadmin` credentials at a later time:
```sh
terraform output
terraform output -raw password
```
1. Login to the various nodes via SSH
Bastion:
```sh
ssh -i $(terraform output -raw ssh_private_key_file) root@$(terraform output -raw bastion_ip)
```
## Experimental Statement
Bootstrap Node:
```sh
ssh -i $(terraform output -raw ssh_private_key_file) core@$(terraform output -json openshift_bootstrap_ip | jq -r '.[0]')
```
Three Control Plane Nodes (default, 0-2):
```sh
ssh -i $(terraform output -raw ssh_private_key_file) core@$(terraform output -json openshift_controlplane_ips | jq -r '.[0].[0]') # Change the last 0 for other nodes
```
Two Worker Nodes (default, 0-1):
```sh
ssh -i $(terraform output -raw ssh_private_key_file) core@$(terraform output -json openshift_worker_ips | jq -r '.[0].[0]') # Change the last 0 for other nodes
```
1. Access the console (MacOS, Linux)
```sh
open $(terraform output -raw console)
```
You will have to navigate your browser settings to access the URL with an invalid certificate.
1. View OpenShift nodes with Kubernetes CLI (`kubectl`)
This repository is [Experimental](https://github.com/packethost/standards/blob/master/experimental-statement.md)!
```sh
% kubectl --kubeconfig $(terraform output -raw kubeconfig) get nodes
NAME STATUS ROLES AGE VERSION
master-0.mos.meyu.us Ready control-plane,master 6h28m v1.25.16+306a47e
master-1.mos.meyu.us Ready control-plane,master 6h28m v1.25.16+306a47e
master-2.mos.meyu.us Ready control-plane,master 6h28m v1.25.16+306a47e
worker-0.mos.meyu.us Ready worker 6h17m v1.25.16+306a47e
worker-1.mos.meyu.us Ready worker 6h14m v1.25.16+306a47e
```
---
<a name="3nodedeployment"><sup>1</sup></a> As of OpenShift Container Platform 4.5 you can [deploy three-node clusters on bare metal](https://docs.openshift.com/container-platform/4.5/installing/installing_bare_metal/installing-bare-metal.html#installation-three-node-cluster_installing-bare-metal). Setting `count_compute=0` will support deployment of a 3-node cluster. [↩](#openshift-via-terraform-on-equinix-metal)
<a name="3nodedeployment"><sup>1</sup></a> As of OpenShift Container Platform 4.12 you can [deploy three-node clusters on bare metal](https://docs.openshift.com/container-platform/4.12/installing/installing_bare_metal/installing-bare-metal.html#installing-bare-metal). Setting `count_compute=0` will support deployment of a 3-node cluster. [↩](#openshift-via-terraform-on-equinix-metal)

0 comments on commit 4c98ca1

Please sign in to comment.