From abb26841560b1409fec5447c33ffaccf4208e1a1 Mon Sep 17 00:00:00 2001 From: root Date: Wed, 18 Jan 2023 10:56:59 +0100 Subject: [PATCH 1/5] add V4_CFG_CERTS and prevent viya4-orders-cli if order files are already present --- docs/CONFIG-VARS.md | 1 + docs/user/DockerVolumeMounts.md | 1 + roles/vdm/tasks/assets.yaml | 14 ++++++++++++++ 3 files changed, 16 insertions(+) diff --git a/docs/CONFIG-VARS.md b/docs/CONFIG-VARS.md index d5c7a373..0bc9f224 100644 --- a/docs/CONFIG-VARS.md +++ b/docs/CONFIG-VARS.md @@ -119,6 +119,7 @@ When V4_CFG_MANAGE_STORAGE is set to `true`, a new storage class is created: sas | V4_CFG_ORDER_NUMBER | SAS software order ID | string | | true | | viya | | V4_CFG_CADENCE_NAME | Cadence name | string | lts | false | [stable,lts] | viya | | V4_CFG_CADENCE_VERSION | Cadence version | string | "2022.09" | true | This value must be surrounded by quotation marks to accommodate the updated SAS Cadence Version format. If the value is not quoted the deployment will fail. | viya | +| V4_CFG_CERTS | Path to pre-downloaded certificates | string | | false | Leave blank to download certificates | viya | | V4_CFG_DEPLOYMENT_ASSETS | Path to pre-downloaded deployment assets | string | | false | Leave blank to download deployment assets | viya | | V4_CFG_LICENSE | Path to pre-downloaded license file | string | | false| Leave blank to download license file | viya | diff --git a/docs/user/DockerVolumeMounts.md b/docs/user/DockerVolumeMounts.md index f8e2af58..ebae0fdf 100644 --- a/docs/user/DockerVolumeMounts.md +++ b/docs/user/DockerVolumeMounts.md @@ -21,6 +21,7 @@ Ansible vars to docker volume mounts mappings. For full listing of config vars s | Ansible Var | Docker Mount | | :--- | ---: | +| V4_CFG_CERTS | `--volume :/config/v4_cfg_certs `| | V4_CFG_DEPLOYMENT_ASSETS | `--volume :/config/v4_cfg_deployment_assets `| | V4_CFG_LICENSE | `--volume :/config/v4_cfg_license `| diff --git a/roles/vdm/tasks/assets.yaml b/roles/vdm/tasks/assets.yaml index 51cb694d..700d0182 100644 --- a/roles/vdm/tasks/assets.yaml +++ b/roles/vdm/tasks/assets.yaml @@ -4,6 +4,7 @@ url: "https://github.com/sassoftware/viya4-orders-cli/releases/download/{{ V4_ORDERS_CLI_VERSION }}/viya4-orders-cli_{{ hostvars[inventory_hostname]['ansible_system']|lower }}_amd64" dest: "{{ tmpdir.path }}/viya4-orders-cli" mode: "0755" + when: V4_CFG_LICENSE is none or V4_CFG_DEPLOYMENT_ASSETS is none or V4_CFG_CERTS is none tags: - install - uninstall @@ -48,6 +49,8 @@ environment: CLIENTCREDENTIALSID: "{{ V4_CFG_SAS_API_KEY | string | b64encode }}" CLIENTCREDENTIALSSECRET: "{{ V4_CFG_SAS_API_SECRET | string | b64encode }}" + when: + - V4_CFG_CERTS is none tags: - install - uninstall @@ -123,6 +126,17 @@ - uninstall - update +- name: assets - Copy user-provided certs file + copy: + src: "{{ V4_CFG_CERTS }}" + dest: "{{ LICENSE_DIRECTORY }}/certs" + when: + - V4_CFG_CERTS is not none + tags: + - install + - uninstall + - update + - name: assets - Set LICENSE_CONTENT set_fact: LICENSE_CONTENT: "{{ lookup('file', '{{ LICENSE_DIRECTORY }}/license.jwt') }}" From 1feb0b5456421471c0856e7ffcb1f7f748898fa2 Mon Sep 17 00:00:00 2001 From: root Date: Wed, 18 Jan 2023 10:57:20 +0100 Subject: [PATCH 2/5] wip: air gap documentation --- docs/user/AirGapInstallation.md | 220 ++++++++++++++++++++++++++++++++ 1 file changed, 220 insertions(+) create mode 100644 docs/user/AirGapInstallation.md diff --git a/docs/user/AirGapInstallation.md b/docs/user/AirGapInstallation.md new file mode 100644 index 00000000..cfe5eee3 --- /dev/null +++ b/docs/user/AirGapInstallation.md @@ -0,0 +1,220 @@ +# Air Gap Installation + +> This is still a work in progress, as baseline installation still requires an internet access, because it downloads charts from bitnami. + +Installation without (full) internet access requires additionnal step, that are described below. + +The main points are: +- download order from internet +- download sas repos corresponding to the order +- push all sas images to a private registry +- clone viya4-deployment github to build the docker image +- start a private web server to serve the order +- install baseline +- install viya + +## Prereqs + +- Docker [installed on your workstation](Dependencies.md#docker). + +## Preparation + +### Download Order + +Installation requires specific files to download from SAS internet web site, looking like this: +- certificates: `SASViyaV4_XXXXXX_certs.zip` +- deployment assets: `SASViyaV4_XXXXXX_3_stable_2022.12_20230113.1673622017934_deploymentAssets_2023-01-13T154226.tgz` +- license: `SASViyaV4_XXXXXX_3_stable_2022.12_license_2023-01-09T112933.jwt` + +First, fill out the required order information in `ansible-vars.yaml` file, as described in [Customize Input Values](../../README.md#customize-input-values).: +- `V4_CFG_SAS_API_KEY` +- `V4_CFG_SAS_API_SECRET` +- `V4_CFG_ORDER_NUMBER` +- `V4_CFG_CADENCE_NAME` +- `V4_CFG_CADENCE_VERSION` + +Next, download `viya4-orders-cli` from `https://github.com/sassoftware/viya4-orders-cli` releases: + +```bash +wget https://github.com/sassoftware/viya4-orders-cli/releases/download/1.5.0/viya4-orders-cli_linux_amd64 +``` + +Last, download fies from SAS internet web site to the `./config` folder: + +```bash +cd config + +# read order variables +cat ansible-vars.yaml | yq '["key",.V4_CFG_SAS_API_KEY],["secret",.V4_CFG_SAS_API_SECRET],["order",.V4_CFG_ORDER_NUMBER],["name",.V4_CFG_CADENCE_NAME],["version",.V4_CFG_CADENCE_VERSION]' -rc | tr -d '[]"' | tr ',' '=' > order.env +source ./order.env + +# prepare client credentials key and secret +export CLIENTCREDENTIALSID=$( echo -n "$key" | base64 ) +export CLIENTCREDENTIALSSECRET=$( echo -n "$secret" | base64 ) + +# perform download +../viya4-orders-cli_linux_amd64 certificates $order -o json > certs.json.tmp && mv certs.json.tmp certs.json +../viya4-orders-cli_linux_amd64 deploymentAssets $order $name $version -o json > deploymentAssets.json.tmp && mv deploymentAssets.json.tmp deploymentAssets.json +../viya4-orders-cli_linux_amd64 license $order $name $version -o json > license.json.tmp && mv license.json.tmp license.json +``` + +Keep the json files near the downloaded files as they contain the full name of the downloaded files. + +### Download SAS Repos + +To download files into `./download` folder, using order from `./config`: + +```bash +# read order variables +source ./config/order.env +release=$( cat config/deploymentAssets.json | jq .cadenceRelease -r ) + +# prepare download variables +DEPLOYMENT_DATA=$( cat certs.json | jq .assetLocation -r ) +DEPLOYMENT_DATA=$PWD/config/${DEPLOYMENT_DATA##*/} +PARALLEL_DOWNLOAD=10 +CADENCE=$name-$version +RELEASE=$release + +# download SAS mirror manager +cd download +[ -x mirrormgr ] || { + proxy wget https://support.sas.com/installation/viya/4/sas-mirror-manager/lax/mirrormgr-linux.tgz + tar -xvf mirrormgr-linux.tgz +} + +# download SAS repos +./mirrormgr mirror registry --path ../sas_repos --cadence $CADENCE --release $RELEASE --deployment-data $DEPLOYMENT_DATA --workers $PARALLEL_DOWNLOAD +``` + +This will download several dozen gigabytes and can take several hours to complete. + +### Push all images to a private registry + +As explained in SAS documentation, sas mirror mananager can also push all images to a private registry: + +```bash +# read order variables +source ./config/order.env + +# prepare download variables +DEPLOYMENT_DATA=$( cat config/certs.json | jq .assetLocation -r ) +DEPLOYMENT_DATA=$PWD/config/${DEPLOYMENT_DATA##*/} +REGISTRY=registry.localdomain:5000 + +cd download +./mirrormgr mirror registry --path ../sas_repos --deployment-data $DEPLOYMENT_DATA --destination $REGISTRY --push-only +``` + +Modify above script according to your needs, like registry username and password, ... + +### Docker image + +Run the following command to create the `viya4-deployment` Docker image using the provided [Dockerfile](../../Dockerfile) + +```bash +docker build -t viya4-deployment . +``` +The Docker image `viya4-deployment` will contain ansible, cloud provider cli's and 'kubectl' executables. The Docker entrypoint for the image is `ansible-playbook` that will be run with sub-commands in the subsequent steps. + +> Build does not work if done behind a proxy, as one of its component (azure?) installation script does not handle proxy settings. +> The solution is to remove all AWS, Azure and GCP references to the Dockerfile before building the image. + +> If it is required to add CA Certificates to the image: +> - create a new extra folder `/usr/local/share/ca-certificates/extra/` +> - copy all CA certificates in that folder - names MUST end with .crt +> - docker build will automatically load them and create `/etc/ssl/certs/ca-certificates.crt` + +## Running + +### Serve Order Files + +As installation process needs to download the order, start a very simple web server to serve the order on port 80: + +```bash +docker run --rm --network host --name repos-sas ${1:--d} \ + -v $PWD/sas_repos:/sas_repos:ro \ + -w /sas_repos \ + python:3-alpine \ + python -m http.server 80 +``` + +### Docker Volume Mounts + +All configs needed by ansible are also needed to be mounted into the docker container. In general any file/folder path set via an ansible flag are equivalent to the file/folder being mounted to the docker container at `/config/`. + +See [Docker Volume Mapping](DockerVolumeMounts.md) for the full list of docker volume mappings. + +Examples: + +- The ansible flag `-e KUBECONFIG` is equivalent to `--volume :/config/kubeconfig` when running the docker container +- The ansible flag `-e JUMP_SVR_PRIVATE_KEY` is equivalent to `--volume :/config/jump_svr_private_key` when running the docker container +- The ansible flag `-e V4_CFG_SITEDEFAULT` is equivalent to `--volume :/config/v4_cfg_sitedefault` when running the docker container + +Below are the only exceptions: + +| Ansible Flag | Docker Mount Path | Description | Required | +| :--- | :--- | :--- | ---: | +| -e BASE_DIR | `/data` | local folder in which all the generated files can be stored. If you do not wish to save the files, this can be omitted | false | +| --vault-password-file | `/config/vault_password_file` | Full path to file containing the Ansible vault password | false | + +### Variable Definitions (ansible-vars.yaml) File + +Prepare your `ansible-vars.yaml` file, as described in [Customize Input Values](../../README.md#customize-input-values). + +## Running + +Declare the Actions and Task to be performed + +### Actions + +Actions are used to install or uninstall software. One must be set when running the playbook. + +| Name | Description | +| :--- | ---: | +| install | Installs the stack required for the specified tasks | +| uninstall | Uninstalls the stack required for the specified tasks | + +### Tasks + +Any number of tasks can be run at the same time. An action can run against a single task or all tasks. + +| Name | Description | +| :--- | :--- | +| baseline | Installs cluster level tooling needed for all viya deployments. These may include, cert-manager, ingress-nginx, nfs-client-provisioners and more. | +| viya | Deploys viya | +| cluster-logging | Installs cluster-wide logging using the [viya4-monitoring-kubernetes](https://github.com/sassoftware/viya4-monitoring-kubernetes) project. | +| cluster-monitoring | Installs cluster-wide monitoring using the [viya4-monitoring-kubernetes](https://github.com/sassoftware/viya4-monitoring-kubernetes) project. | +| viya-monitoring | Installs viya namespace level monitoring using the [viya4-monitoring-kubernetes](https://github.com/sassoftware/viya4-monitoring-kubernetes) project. | + +### Example + +```bash +# read order variables +certs=$( cat config/certs.json | jq .assetLocation -r ) +deploymentAssets=$( cat config/deploymentAssets.json | jq .assetLocation -r ) +license=$( cat config/license.json | jq .assetLocation -r ) +certs=${certs##*/} +deploymentAssets=${deploymentAssets##*/} +license=${license##*/} + +# read other variables +cluster_name=$( cat config/ansible-vars.yaml | yq .CLUSTER_NAME -re ) +namespace=$( cat config/ansible-vars.yaml | yq .NAMESPACE -re ) + +# copy site-config to data folder +rsync -a config/site-config/ data/$cluster_name/$namespace/site-config/ + +# perform installation +docker run --rm -it --network=host --name sas-deployment --group-add root --user 0:0 \ + -v $PWD/config/$certs:/config/v4_cfg_certs:ro \ + -v $PWD/config/$deploymentAssets:/config/v4_cfg_deployment_assets:ro \ + -v $PWD/config/$license:/config/v4_cfg_license:ro \ + -v $PWD/config/ansible-vars.yaml:/config/config:ro \ + -v $PWD/data:/data \ + -v $PWD/viya4-deployment:/viya4-deployment.new:ro \ + -v ~/.kube/config:/config/kubeconfig:ro \ + -e SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt \ + viya4-deployment \ + --tags baseline,viya,install +``` From 15b646ab18660451bc25eff87ace00500cc52023 Mon Sep 17 00:00:00 2001 From: root Date: Wed, 18 Jan 2023 11:19:46 +0100 Subject: [PATCH 3/5] add V4_CFG_URL to configure repository warehouse url --- docs/CONFIG-VARS.md | 1 + docs/user/AirGapInstallation.md | 7 +++++++ roles/multi-tenancy/defaults/main.yml | 1 + roles/vdm/defaults/main.yaml | 1 + roles/vdm/tasks/orchestration.yaml | 4 ++++ 5 files changed, 14 insertions(+) diff --git a/docs/CONFIG-VARS.md b/docs/CONFIG-VARS.md index 0bc9f224..90b05d99 100644 --- a/docs/CONFIG-VARS.md +++ b/docs/CONFIG-VARS.md @@ -122,6 +122,7 @@ When V4_CFG_MANAGE_STORAGE is set to `true`, a new storage class is created: sas | V4_CFG_CERTS | Path to pre-downloaded certificates | string | | false | Leave blank to download certificates | viya | | V4_CFG_DEPLOYMENT_ASSETS | Path to pre-downloaded deployment assets | string | | false | Leave blank to download deployment assets | viya | | V4_CFG_LICENSE | Path to pre-downloaded license file | string | | false| Leave blank to download license file | viya | +| V4_CFG_URL | Software order server | string | https://ses.sas.download/ses | false | viya | ## SAS API Access diff --git a/docs/user/AirGapInstallation.md b/docs/user/AirGapInstallation.md index cfe5eee3..2bf44bd9 100644 --- a/docs/user/AirGapInstallation.md +++ b/docs/user/AirGapInstallation.md @@ -139,6 +139,13 @@ docker run --rm --network host --name repos-sas ${1:--d} \ python -m http.server 80 ``` +Ensure the web server can be reached from any kube node, as deployement will be executed in kubernetes: +- use a HOST that can be resolved on all nodes +- open the required flows in the firewall if needed +- test access to, `shipped.mc`, using url like http://HOST/cadences/shipped.mc + +Once working, update `V4_CFG_URL` accordingly (`http://HOST`) in `ansible-vars.yaml` file. + ### Docker Volume Mounts All configs needed by ansible are also needed to be mounted into the docker container. In general any file/folder path set via an ansible flag are equivalent to the file/folder being mounted to the docker container at `/config/`. diff --git a/roles/multi-tenancy/defaults/main.yml b/roles/multi-tenancy/defaults/main.yml index 86c7b1ff..9aae07a5 100644 --- a/roles/multi-tenancy/defaults/main.yml +++ b/roles/multi-tenancy/defaults/main.yml @@ -3,6 +3,7 @@ # Updating HOST to remove https V4_CFG_CR_URL: https://cr.sas.com V4_CFG_CR_HOST: '{{ V4_CFG_CR_URL | regex_replace("^https?:\/\/(.*)\/?", "\1") }}' +V4_CFG_URL: https://ses.sas.download/ses # Multi-tenant is enabled within SAS Viya deployment V4MT_ENABLE: false diff --git a/roles/vdm/defaults/main.yaml b/roles/vdm/defaults/main.yaml index 22aee2fc..666c1236 100644 --- a/roles/vdm/defaults/main.yaml +++ b/roles/vdm/defaults/main.yaml @@ -8,6 +8,7 @@ V4_CFG_DEPLOYMENT_ASSETS: null V4_CFG_ORDER_NUMBER: null V4_CFG_CADENCE_NAME: lts V4_CFG_CADENCE_VERSION: "2022.09" +V4_CFG_URL: https://ses.sas.download/ses V4_CFG_CR_USER: null V4_CFG_CR_PASSWORD: null diff --git a/roles/vdm/tasks/orchestration.yaml b/roles/vdm/tasks/orchestration.yaml index e3831ee8..4952150d 100644 --- a/roles/vdm/tasks/orchestration.yaml +++ b/roles/vdm/tasks/orchestration.yaml @@ -217,6 +217,7 @@ --image-registry "{{ V4_CFG_CR_HOST }}" --deployment-data "{{ ORCHESTRATION_TOOLING_DIRECTORY }}/data/license/certs.zip" --user-content "{{ ORCHESTRATION_TOOLING_DIRECTORY }}/data/" + --repository-warehouse "{{V4_CFG_URL}}" args: chdir: "{{ ORCHESTRATION_TOOLING_DIRECTORY }}" register: sasdeployment @@ -251,6 +252,7 @@ --image-registry {{ V4_CFG_CR_HOST }} --deployment-data /data/license/certs.zip --user-content /data + --repository-warehouse "{{V4_CFG_URL}}" register: sasdeployment - name: orchestration - Write SAS Viya deployment manifest copy: @@ -327,6 +329,7 @@ --image-registry "{{ V4_CFG_CR_HOST }}" --deployment-data "{{ ORCHESTRATION_TOOLING_DIRECTORY }}/data/license/certs.zip" --user-content "{{ ORCHESTRATION_TOOLING_DIRECTORY }}/data/" + --repository-warehouse "{{V4_CFG_URL}}" args: chdir: "{{ ORCHESTRATION_TOOLING_DIRECTORY }}" register: sasdeployment @@ -360,6 +363,7 @@ --image-registry {{ V4_CFG_CR_HOST }} --deployment-data /data/license/certs.zip --user-content /data + --repository-warehouse "{{V4_CFG_URL}}" register: sasdeployment - name: orchestration - Write SAS Viya uninstall manifest copy: From db0ab3f08807f79171cb71e2f91d67199f4f15e2 Mon Sep 17 00:00:00 2001 From: root Date: Mon, 6 Feb 2023 12:15:45 +0100 Subject: [PATCH 4/5] fix V4_CFG_CERTS target to .zip --- roles/vdm/tasks/assets.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/roles/vdm/tasks/assets.yaml b/roles/vdm/tasks/assets.yaml index 700d0182..66322cb1 100644 --- a/roles/vdm/tasks/assets.yaml +++ b/roles/vdm/tasks/assets.yaml @@ -129,7 +129,7 @@ - name: assets - Copy user-provided certs file copy: src: "{{ V4_CFG_CERTS }}" - dest: "{{ LICENSE_DIRECTORY }}/certs" + dest: "{{ LICENSE_DIRECTORY }}/certs.zip" when: - V4_CFG_CERTS is not none tags: From d742bcb4b83d186fa0938263037520ebb6b1ca22 Mon Sep 17 00:00:00 2001 From: xtian Date: Wed, 3 May 2023 09:18:36 +0200 Subject: [PATCH 5/5] fix remove duplicate ansible var from last merge --- docs/user/DockerVolumeMounts.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/user/DockerVolumeMounts.md b/docs/user/DockerVolumeMounts.md index 68c6cf59..f5a50e82 100644 --- a/docs/user/DockerVolumeMounts.md +++ b/docs/user/DockerVolumeMounts.md @@ -21,7 +21,6 @@ Ansible vars to docker volume mounts mappings. For full listing of config vars s | Ansible Var | Docker Mount | | :--- | ---: | -| V4_CFG_CERTS | `--volume :/config/v4_cfg_certs `| | V4_CFG_DEPLOYMENT_ASSETS | `--volume :/config/v4_cfg_deployment_assets `| | V4_CFG_LICENSE | `--volume :/config/v4_cfg_license `| | V4_CFG_CERTS | `--volume :/config/v4_cfg_certs `|