Skip to content

Commit

Permalink
docs: (PSKD-704) Update refs to GCP in Docs (#221)
Browse files Browse the repository at this point in the history
* docs: (PSKD-704) Update GCP refs in documentation
  • Loading branch information
riragh authored Sep 12, 2024
1 parent f53d5e4 commit 2ccb8a5
Show file tree
Hide file tree
Showing 7 changed files with 42 additions and 42 deletions.
24 changes: 12 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# SAS Viya 4 Infrastructure as Code (IaC) for Google Cloud Platform (GCP)
# SAS Viya 4 Infrastructure as Code (IaC) for Google Cloud

## Overview

This project contains Terraform scripts to provision Google GCP infrastructure resources required to deploy SAS Viya 4 platform products. Here is a list of resources this project can create -
This project contains Terraform scripts to provision Google Cloud infrastructure resources required to deploy SAS Viya 4 platform products. Here is a list of resources this project can create -

>- VPC Network and Network Firewalls
>- Managed Google Kubernetes Engine (GKE) cluster
Expand All @@ -13,14 +13,14 @@ This project contains Terraform scripts to provision Google GCP infrastructure r
[<img src="./docs/images/viya4-iac-gcp-diag.png" alt="Architecture Diagram" width="750"/>](./docs/images/viya4-iac-gcp-diag.png?raw=true)

Once the cloud resources are provisioned, see the [viya4-deployment](https://github.com/sassoftware/viya4-deployment) repo to deploy SAS Viya 4 platform products. If you need more information on the SAS Viya 4 platform products refer to the official [SAS&reg; Viya&reg; platform Operations](https://documentation.sas.com/?cdcId=itopscdc&cdcVersion=default&docsetId=itopswlcm&docsetTarget=home.htm) documentation for more details.
Once the cloud resources are provisioned, see the [viya4-deployment](https://github.com/sassoftware/viya4-deployment) repository to deploy SAS Viya 4 platform products. If you need more information on the SAS Viya 4 platform products refer to the official [SAS&reg; Viya&reg; platform Operations](https://documentation.sas.com/?cdcId=itopscdc&cdcVersion=default&docsetId=itopswlcm&docsetTarget=home.htm) documentation for more details.

## Prerequisites

Operational knowledge of
- [Terraform](https://www.terraform.io/intro/index.html)
- [Docker](https://www.docker.com/)
- [Google Cloud Platform](https://cloud.google.com/)
- [Google Cloud](https://cloud.google.com/)
- [Kubernetes](https://kubernetes.io/docs/concepts/)

### Required
Expand All @@ -46,28 +46,28 @@ Operational knowledge of
Run these commands in a Terminal session:

```bash
# clone this repo
# clone this repository
git clone https://github.com/sassoftware/viya4-iac-gcp

# move to directory
cd viya4-iac-gcp
```

### Authenticating Terraform to access GCP
### Authenticating Terraform to access Google Cloud

See [Terraform GCP Authentication](./docs/user/TerraformGCPAuthentication.md) for details.
See [Terraform Google Cloud Authentication](./docs/user/TerraformGCPAuthentication.md) for details.

### Customize Input Values

Create a file named `terraform.tfvars` to customize any input variable value documented in the [CONFIG-VARS.md](docs/CONFIG-VARS.md) file. For starters, you can copy one of the provided example variable definition files in `./examples` folder. For more details on the variables declared refer to the [CONFIG-VARS.md](docs/CONFIG-VARS.md) file.

**NOTE:** You will need to update the `cidr_blocks` in the [variables.tf](variables.tf) file to allow traffic from your current network. Without these rules, access to the cluster will only be allowed via the GCP Console.
**NOTE:** You will need to update the `cidr_blocks` in the [variables.tf](variables.tf) file to allow traffic from your current network. Without these rules, access to the cluster will only be allowed via the Google Cloud Console.

When using a variable definition file other than `terraform.tfvars`, see [Advanced Terraform Usage](docs/user/AdvancedTerraformUsage.md) for additional command options.

## Creating and Managing the Cloud Resources

Create and manage the GCP cloud resources by either
Create and manage the Google Cloud resources by either

- using [Terraform](docs/user/TerraformUsage.md) directly on your workstation, or
- using a [Docker container](docs/user/DockerUsage.md).
Expand All @@ -87,11 +87,11 @@ See [troubleshooting](./docs/Troubleshooting.md) page.
## Additional Resources

### GCP
### Google Cloud

- Google Cloud CLI - https://cloud.google.com/sdk/gcloud
- Terraform on GCP - https://cloud.google.com/docs/terraform
- Terraform and GCP Service Accounts - https://medium.com/@gmusumeci/how-to-create-a-service-account-for-terraform-in-gcp-google-cloud-platform-f75a0cf918d1
- Terraform on Google Cloud - https://cloud.google.com/docs/terraform
- Terraform and Google Cloud Service Accounts - https://medium.com/@gmusumeci/how-to-create-a-service-account-for-terraform-in-gcp-google-cloud-platform-f75a0cf918d1
- GKE intro - https://cloud.google.com/kubernetes-engine

### Terraform
Expand Down
24 changes: 12 additions & 12 deletions docs/CONFIG-VARS.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Supported configuration variables are listed in the table below. All variables
- [List of valid configuration variables](#list-of-valid-configuration-variables)
- [Table of Contents](#table-of-contents)
- [Required Variables](#required-variables)
- [GCP Authentication](#gcp-authentication)
- [Google Cloud Authentication](#gcp-authentication)
- [Admin Access](#admin-access)
- [Networking](#networking)
- [Use Existing](#use-existing)
Expand All @@ -31,21 +31,21 @@ Terraform input variables can be set in the following ways:

| Name | Description | Type | Default | Notes |
| :--- | :--- | :--- | :--- | :--- |
| prefix | A prefix used in the name of all the GCP resources created by this script. | string | | The prefix string must start with a lowercase letter and contain only lowercase alphanumeric characters and dashes (-), but cannot end with a dash. |
| location | The GCP Region (for example "us-east1") or GCP Zone (for example "us-east1-b") to provision all resources in this script. | string | | See [this topic](user/Locations.md) on how to chose a region or a zone. |
| project | The ID of the GCP Project to use | string | | |
| prefix | A prefix used in the name of all the Google Cloud resources created by this script. | string | | The prefix string must start with a lowercase letter and contain only lowercase alphanumeric characters and dashes (-), but cannot end with a dash. |
| location | The Google Cloud Region (for example "us-east1") or Google Cloud Zone (for example "us-east1-b") to provision all resources in this script. | string | | See [this topic](user/Locations.md) on how to chose a region or a zone. |
| project | The ID of the Google Cloud Project to use | string | | |
| service_account_keyfile | Filename of the Service Account JSON file | string | Not required when running on a Google Cloud VM that is associated with the Service Account |

## GCP Authentication
## Google Cloud Authentication

The Terraform process manages GCP resources on your behalf. In order to do so, it needs to know the credentials for a GCP identity with the required permissions.
The Terraform process manages Google Cloud resources on your behalf. In order to do so, it needs to know the credentials for a Google Cloud identity with the required permissions.

For more detailed information on what is needed see [Authenticating Terraform to access GCP](https://github.com/sassoftware/viya4-iac-gcp/blob/main/docs/user/TerraformGCPAuthentication.md)
For more detailed information on what is needed see [Authenticating Terraform to access Google Cloud](https://github.com/sassoftware/viya4-iac-gcp/blob/main/docs/user/TerraformGCPAuthentication.md)

## Admin Access

By default, the API of the GCP resources that are being created are only accessible through authenticated GCP clients (e.g. the Google Cloud Portal, the `gcloud` CLI, the Google Cloud Shell, etc.)
To allow access for other administrative client applications (for example `kubectl`, `psql`, etc.), you need to open up the GCP firewall to allow access from your source IPs.
By default, the API of the Google Cloud resources that are being created are only accessible through authenticated Google Cloud clients (e.g. the Google Cloud Portal, the `gcloud` CLI, the Google Cloud Shell, etc.)
To allow access for other administrative client applications (for example `kubectl`, `psql`, etc.), you need to open up the Google Cloud firewall to allow access from your source IPs.

To do set these permissions as part of this Terraform script, specify ranges of IP addresses in [CIDR notation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing). Contact your Network Administrator to find the public CIDR range of your network.

Expand Down Expand Up @@ -94,11 +94,11 @@ subnet_names = {
}
```

Note: The subnets for filestore and database can not the pre-created. GCP creates the subnets as part of the services.
Note: The subnets for filestore and database can not the pre-created. Google Cloud creates the subnets as part of the services.

## General

The application of a Kubernetes version in GCP has some limitations when assigning channels and versions to the cluster. The doc outlining on these limitations can be found in the [Kubernetes Versions](user/KubernetesVersions.md) guide.
The application of a Kubernetes version in Google Cloud has some limitations when assigning channels and versions to the cluster. The documentation that describes these limitations can be found in the [Kubernetes Versions](user/KubernetesVersions.md) guide.

| Name | Description | Type | Default | Notes |
| :--- | ---: | ---: | ---: | ---: |
Expand All @@ -114,7 +114,7 @@ The application of a Kubernetes version in GCP has some limitations when assigni
| create_jump_public_ip | Add public ip to jump VM | bool | true | |
| jump_vm_admin | OS Admin User for the Jump VM | string | "jumpuser" | |
| jump_rwx_filestore_path | File store mount point on Jump server | string | "/viya-share" | |
| tags | Map of common tags to be placed on all GCP resources created by this script | map | {} | |
| tags | Map of common tags to be placed on all Google Cloud resources created by this script | map | {} | |
| ssh_public_key | File name of public ssh key for jump and nfs VM | string | null | Required with `create_jump_vm=true` or `storage_type=standard` |
| cluster_api_mode | Public or private IP for the cluster api| string|"public"|Valid Values: "public", "private" |

Expand Down
6 changes: 3 additions & 3 deletions docs/user/DockerUsage.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,14 +31,14 @@ docker build --build-arg INSTALL_COMPONENTS="cloud-spanner-emulator" -t viya4-ia
```


### Service Account Keyfile for GCP Authentication
### Service Account Keyfile for Google Cloud Authentication

Prepare a file with GCP authentication info, as described in [Authenticating Terraform to access GCP](./TerraformGCPAuthentication.md) and store it outside of this repo in a secure file, for example `$HOME/.viya4-tf-gcp-service-account.json`.
Prepare a file with Google Cloud authentication information, as described in [Authenticating Terraform to access Google Cloud](./TerraformGCPAuthentication.md) and store it outside of this repository in a secure file, for example `$HOME/.viya4-tf-gcp-service-account.json`.

### Docker Volume Mounts

Add volume mounts to the `docker run` command for all files and directories that must be accessible from inside the container.
- `--volume=$HOME/.viya4-tf-gcp-service-account.json:/.viya4-tf-gcp-service-account.json` Service Account Key file for GCP authentication
- `--volume=$HOME/.viya4-tf-gcp-service-account.json:/.viya4-tf-gcp-service-account.json` Service Account Key file for Google Cloud authentication
- `--volume=$HOME/.ssh:/.ssh` for [`ssh_public_key`](../CONFIG-VARS.md#required-variables) variable in the `terraform.tfvars` file
- `--volume=$(pwd):/workspace` for local directory where `terraform.tfvars` file resides and where `terraform.tfstate` file will be written. To grant Docker, permission to write to the local directory use [`--user` option](https://docs.docker.com/engine/reference/run/#user)

Expand Down
2 changes: 1 addition & 1 deletion docs/user/KubernetesVersions.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Kubernetes Versions

Setting versions within the Google Cloud Platform (GCP) environment is slightly different from setting a version within other cloud providers
Setting versions within the Google Cloud environment is slightly different from setting a version within other cloud providers

There are two scenarios that are supported. These are:

Expand Down
2 changes: 1 addition & 1 deletion docs/user/Locations.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
## Resource Locations

Google Cloud Platform resources are hosted in different data centers worldwide, divided into [Regions and Zones](https://cloud.google.com/compute/docs/regions-zones).
Google Cloud resources are hosted in different data centers worldwide, divided into [Regions and Zones](https://cloud.google.com/compute/docs/regions-zones).

You control the location of your Viya4 IAC resources by setting the `location` variable to either a Region or a Zone.

Expand Down
22 changes: 11 additions & 11 deletions docs/user/TerraformGCPAuthentication.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# Authenticating Terraform to access GCP
# Authenticating Terraform to access Google Cloud

Terraform creates and destroys resources in the Google Cloud Platform on your behalf.
In order to do so, it needs to authenticate itself to GCP with the appropriate permissions.
Terraform creates and destroys resources in Google Cloud on your behalf.
In order to do so, it needs to authenticate itself to Google Cloud with the appropriate permissions.

This project uses a GCP Service Account to authenticate with GCP. You will need a Service Account with the appropriate permissions. You can use an existing Service Account, or preferably create a dedicated Service Account.
This project uses a Google Cloud Service Account to authenticate with Google Cloud. You will need a Service Account with the appropriate permissions. You can use an existing Service Account, or preferably create a dedicated Service Account.

## Running Terraform outside Google Cloud

Expand All @@ -14,9 +14,9 @@ If you are running terraform outside of Google Cloud, generate a service account
If you are running terraform on a VM in Google Cloud, you can [configure that VM instance to use your Service Account](https://cloud.google.com/compute/docs/access/create-enable-service-accounts-for-instances#using). This will allow Terraform to authenticate to Google Cloud without having to bake in a separate credential/authentication file. Ensure that the scope of the VM is set to or includes https://www.googleapis.com/auth/cloud-platform.


## Create a GCP Service Account
## Create a Google Cloud Service Account

How to create a GCP Service Account: https://cloud.google.com/iam/docs/creating-managing-service-accounts
How to create a Google Cloud Service Account: https://cloud.google.com/iam/docs/creating-managing-service-accounts

gcloud CLI Example:

Expand Down Expand Up @@ -44,7 +44,7 @@ The Service Account will need the following [IAM roles](https://cloud.google.com
| `roles/iam.serviceAccountUser` | Service Account User | Terraform Kubernetes Engine Module |
| `roles/resourcemanager.projectIamAdmin` | Project IAM Admin | Terraform Kubernetes Engine Module |

How to modify IAM access to GCP resources: https://cloud.google.com/iam/docs/granting-changing-revoking-access
How to modify IAM access to Google Cloud resources: https://cloud.google.com/iam/docs/granting-changing-revoking-access

gcloud CLI Example:
```bash
Expand Down Expand Up @@ -96,7 +96,7 @@ roles/resourcemanager.projectIamAdmin

## Create the Service Account Keyfile

When running terraform on a workstation outside of the Google Cloud Platform, you persist the Service Account information to a JSON file, and then [specify that file when running terraform](#Terraform-project-variables-to-authenticate-with-GCP).
When running terraform on a workstation outside of Google Cloud, you store the Service Account information in a JSON file, and then [specify that file when running terraform](#Terraform-project-variables-to-authenticate-with-GCP).

Managing key files using the Cloud Console: https://console.cloud.google.com/apis/credentials/serviceaccountkey

Expand All @@ -110,11 +110,11 @@ gcloud iam service-accounts keys create ${SA_KEY_FILE} --iam-account ${SA_NAME}@
chmod 500 ${SA_KEY_FILE} # secure the keyfile
```

## Terraform project variables to authenticate with GCP
## Terraform project variables to authenticate with Google Cloud

As part of your [Terraform input variables](../../README.md#customize-input-values), set these values:

| Name | Description |
| :--- | :--- |
| project | The GCP Project to use |
| service_account_keyfile | Filename of the Service Account JSON file. Alternatively, you can set the `GOOGLE_APPLICATION_CREDENTIAL` environment variable. Note that you do not need to set this variable when running on a GCP VM that is associated with the Service Account. |
| project | The Google Cloud Project to use |
| service_account_keyfile | Filename of the Service Account JSON file. Alternatively, you can set the `GOOGLE_APPLICATION_CREDENTIAL` environment variable. Note that you do not need to set this variable when running on a Google Cloud VM that is associated with the Service Account. |
4 changes: 2 additions & 2 deletions docs/user/TerraformUsage.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@ When using the Terraform CLI, make sure you have all the necessary tools [instal

## Preparation

### Set GCP Authentication
### Set Google Cloud Authentication

Prepare a file with authentication info, as described in [Authenticating Terraform to access GCP](./TerraformGCPAuthentication.md).
Prepare a file with authentication information, as described in [Authenticating Terraform to access Google Cloud](./TerraformGCPAuthentication.md).

### Prepare Variable Definitions (.tfvars) File

Expand Down

0 comments on commit 2ccb8a5

Please sign in to comment.