Installation#

Important

Before you start the setup, ensure that you meet the basic prerequisites.

Note

Manual setup instructions are also available in the Manual Installation section. However, NVIDIA recommends the automated setup because it provides a streamlined installation process with minimal manual intervention.

Download Resources#

Create a directory (for example, ~/cns) to store the resources and navigate to it.
```
mkdir ~/cns
cd ~/cns
```
Download the local-kubernetes-setup-playbook.tar.gz file from the Local Developer Setup resource using an NGC API Key.

Alternatively, download the file from the command line. Replace the <API-KEY> placeholder with your NGC API key:
```
curl -fsSLO "https://api.ngc.nvidia.com/v2/org/nvidia/team/holoscan-for-media/resources/local-developer-setup/versions/0.4.1/files/local-kubernetes-setup-playbook.tar.gz" -H "Authorization: Bearer <API-KEY>"
```
Decompress the downloaded package in the current directory.
```
tar -xzvf local-kubernetes-setup-playbook.tar.gz
```

Install Ansible#

Run the following command to install Ansible:
```
./ansible_setup.sh
```
This script installs Ansible version 8.0.0 along with other necessary components in a virtual Python environment. If the setup succeeds, the script creates a directory .cns with the activate and deactivate scripts.
Open the ~/.bashrc file and add the following lines to suppress some informational Ansible warnings:
```
export ANSIBLE_LOCALHOST_WARNING=False
export ANSIBLE_INVENTORY_UNPARSED_WARNING=False
```
Save the file and return to the shell.

Reload your .bashrc file:
```
source ~/.bashrc
```
To run any Ansible command, activate the Python virtual environment first:
```
source .cns/bin/activate
```
To exit the virtual environment at any time, run:
```
deactivate
```
For more information about Python virtual environments, refer to the venv documentation.

Cluster Installation#

The default config.yaml values are sufficient to run the reference applications in a basic configuration. Edit the file to enable persistent storage or configure a load balancer, because these features are disabled by default. For example, the Chrome Remote Desktop reference application needs persistent storage for its persistent volume claim (PVC), so that remote access still works after its pod restarts.

Use the other settings to do the following, as needed:
- Override the default selection of SR-IOV network interfaces.
- Configure basic GPU time-slicing with a single value.
- Change the shared memory and huge pages configuration.
- Disable platform monitoring.

Run the automation using the following command:

ANSIBLE_LOG_PATH=./install_$(date +'%Y%m%d_%H%M%S').log ansible-playbook h4m_playbook.yaml -e action=install -e "NGC_API_KEY=<API-KEY>" -vv

where:

<API-KEY> is your NGC API key. The playbook does not support legacy NGC API keys.
The -vv flag enables verbose output for debugging. You can change it to -v for less detail or -vvv or -vvvv for increasingly more detailed logs.

Important

During installation, the playbook prompts you for your sudo password.

If the playbook fails with the following message, reboot the system and rerun the playbook:

TASK [Show message if reboot failed] **************************************
ok: [localhost] = {
   "msg": "Reboot failed. Please manually reboot the system and try again."
}

If the system reboots after the playbook applies the SR-IOV Network Node Policy, you must complete the remaining tasks after the reboot. The output looks similar to the following:

TASK [Apply the SR-IOV Network Node Policy] ******************************************************************************************************************
changed: [localhost]

TASK [Wait for NIC Resources to be ready] ********************************************************************************************************************
FAILED - RETRYING: [localhost]: Wait for NIC Resources to be ready (10 retries left).
FAILED - RETRYING: [localhost]: Wait for NIC Resources to be ready (9 retries left).
FAILED - RETRYING: [localhost]: Wait for NIC Resources to be ready (8 retries left).

Wait for the system to reboot and for all components to fully initialize. Then run the following command to complete the remaining tasks:

ANSIBLE_LOG_PATH=./install_$(date +'%Y%m%d_%H%M%S').log ansible-playbook h4m_playbook.yaml --start-at-task="Wait for NIC Resources to be ready" -e action=install -e "NGC_API_KEY=<API-KEY>" -vv

Cluster Uninstallation#

To uninstall the cluster, run the following command:

ANSIBLE_LOG_PATH=./uninstall_$(date +'%Y%m%d_%H%M%S').log ansible-playbook h4m_playbook.yaml -e action=uninstall --ask-become-pass -vv

After you uninstall the cluster, reboot the system to completely remove any components that NVIDIA Cloud Native Stack (CNS) loaded.