One Click Deployment#

Overview#

The NVIDIA-One-Click (NV-One-Click) framework provides tools and scripts to simplify the deployment of Audio2Face-3D on cloud platforms and on-premise infrastructure. It automates the complex setup processes into standardized deployment procedures.

Terms & Definitions

Term	Definition
Cloud platforms	Remote computing services like AWS and Azure that provide computing resources over the internet
On-premise infrastructure	Computing resources located within your organization’s physical facilities
Deployment	The process of setting up and configuring software on computing infrastructure
CNS	Cloud Native Stack - A container orchestration platform for managing containerized applications
Infrastructure as Code	Managing and provisioning infrastructure through code instead of manual processes
Container orchestration	Automating deployment, scaling, and management of containerized applications
Terraform	An open-source infrastructure as code software tool for building and managing cloud resources
Helm	A package manager for Kubernetes that helps install and manage applications

Supported Platforms#

The following cloud platforms are currently supported for Audio2Face-3D deployment:

AWS Cloud Native Stack (CNS) - Amazon Web Services’ container orchestration platform
Azure Cloud Native Stack (CNS) - Microsoft Azure’s container orchestration platform

System Requirements#

This section outlines the hardware and software requirements needed to successfully deploy Audio2Face-3D.

Deployment Machine Specifications#

Operating System:
- Ubuntu 22.04/24.04 LTS (Fully validated and recommended)
- Alternative Linux distributions (Limited validation, use with caution)
Required Software:
- yq (v4.34.1 or later) - Command-line tool for parsing and manipulating YAML files
- jq (1.6 or later) - Command-line tool for parsing and manipulating JSON files
- python3 (3.9.0+) - Programming language runtime
- venv (python3-venv) (3.9.0+) - Tool for creating isolated Python environments
- pip (python3-pip) (22.0.0+) - Python package installer
- terraform (1.5.7) - Infrastructure-as-Code tool for provisioning cloud resources

Note

The deployment package includes two helper scripts: envbuild.sh and install-pre-requisites.sh.

Running either of these scripts will automatically detect and install any missing required software dependencies listed above.

The install-pre-requisites.sh script specifically focuses on installing system dependencies, while envbuild.sh handles both dependency checking and the actual deployment process.

Required Credentials#

Before beginning deployment, ensure you have the following credentials and access requirements in place:

Cloud Deployment Requirements:
- AWS: Administrative access key and secret key
- Azure: Administrative client ID and secret
On-premise Requirements:
- SSH credentials for target systems
Infrastructure-as-Code (IaC) State Management Requirements:
- Terraform state files require a reliable and secure storage backend:
  
  Supported options include Amazon S3, Azure Blob Storage, or local filesystem
  
  For production environments, a remote backend is strongly recommended
  
  For configuration details, see: Terraform Backend Configuration Documentation
- For backend setup instructions specific to your deployment configuration, please consult the README.md file included in the deployment package

Deployment Package Structure#

This section describes the contents and organization of the deployment package.

The NV-One-Click deployment packages for Audio2Face-3D can be downloaded from:

$ ngc registry resource download-version "nim/nvidia/audio2face-3d-nv-one-click-script:1.3.15"

The folder contains deployment packages for both AWS and Azure cloud platforms:

deploy-audio2face3d-aws-cns.tar.gz - Package for AWS deployment
deploy-audio2face3d-azure-cns.tar.gz - Package for Azure deployment

Download the appropriate package based on your target deployment platform.

Open a terminal and navigate to the folder where you downloaded the NV-One-Click deployment packages for Audio2Face-3D:

$ ls *.tar.gz
deploy-audio2face3d-aws-cns.tar.gz  deploy-audio2face3d-azure-cns.tar.gz

Directory Structure:

dist
├── ansible-requirements.yml  # Ansible roles and collections required by playbooks
├── app-tasks.yml            # Tasks executed during application stage
├── config-files             # Configuration files used by tasks
├── config-template.yml      # App Deployer overrides with required configs and credentials
├── envbuild.sh             # Script to setup infrastructure and/or application
├── iac-ref                 # Infrastructure resource definitions in Terraform
├── infra-tasks.yml         # Tasks executed during infrastructure stage
├── install-pre-requisites.sh # Script to setup prerequisites for envbuild.sh
├── MANIFEST                # Information about artifact source
├── modules                 # Terraform modules
├── platform-tasks.yml      # Tasks executed during platform stage
├── playbooks              # Ansible automation scripts
├── README.md              # Installation instructions for App Deployer
└── setup-cns-access.sh    # Script to configure local machine access to CNS clusters

Deployment Process#

Follow these steps in order to deploy Audio2Face-3D on your chosen platform.

1. Extract the deployment package:#

Begin by extracting the deployment files and navigating to the correct directory:

$ tar -xvf deploy-audio2face3d-aws-cns.tar.gz  # Extracts the compressed deployment files
$ cd dist/  # Changes directory to the extracted files

2. Install Pre-requisites#

Install all necessary software dependencies using the provided script:

sudo ls # Need passwordless sudo session
chmod +x ./install-pre-requisites.sh  # Makes the script executable
./install-pre-requisites.sh  # Installs required software

3. Verify Script Usage and Perform Dry Run#

Check available commands:

$ ./envbuild.sh
Usage: ./envbuild.sh (-v|--version)
   or: ./envbuild.sh (-h|--help)
   or: ./envbuild.sh (install/uninstall) (-c|--component <component>) [options]
   or: ./envbuild.sh (force-destroy) [options]
   or: ./envbuild.sh (info) [options]

install/uninstall components:
-c, --component        one or more of all/infra/platform/app, pass arg multiple times for more than one

install/uninstall options:
-f, --config-file      path to file containing config overrides, defaults to config.yml
-i, --skip-infra       skip install/uninstall of infra component
-p, --skip-platform    skip install/uninstall of platform component
-a, --skip-app         skip install/uninstall of app component
-d, --dry-run          don't make any changes, instead, try to predict some of the changes that may occur
-h, --help             provide usage information

force-destroy options:
-f, --config-file      path to file containing config overrides, defaults to config.yml
-h, --help             provide usage information

info options:
-f, --config-file      path to file containing config overrides, defaults to config.yml
-h, --help             provide usage information

Perform a dry run to preview changes:

$ ./envbuild.sh install -c all --dry-run  # Tests deployment without making actual changes
config file (config.yml) not found
please use config-template.yml to create the config.yml
...

4. Configuration Setup#

Set up your deployment configuration by creating and modifying the configuration file:

cp config-template.yml config.yml

For detailed configuration instructions and parameter descriptions, please refer to the README.md documentation.

schema_version: 'x.y.z'  # Version of the configuration schema
name: 'audio2face3d-aws-cns'  # Used for terraform state + resource names
spec:
  infra:
    csp: 'aws'  # Cloud Service Provider selection
    backend: {}  # Configuration for storing terraform state
    provider: {} # Cloud provider-specific settings
  platform: {}   # Kubernetes platform configuration
  app: {}        # Audio2Face-3D application settings

access_cidrs:  # List of IP addresses allowed to access the deployment
- '216.228.112.22/32'  # Your IP address (use: curl -s ifconfig.me)

master:
  size: 'g6e.2xlarge'  # Instance type

# Audio2Face-3D Helm chart: https://registry.ngc.nvidia.com/orgs/nim/teams/nvidia/helm-charts/audio2face-3d
app:    # Application settings
configs:    # Application configuration settings
    app_repo_url: https://helm.ngc.nvidia.com/nim/nvidia/   # Helm repository URL
    app_chart_ref: "audio2face-3d"  # Helm chart reference
    app_chart_version: "{{ lookup('env','A2F_3D_CHART_VERSION') }"  # Helm chart version as environment variable

5. Set Environment Variables#

Configure the necessary environment variables for your chosen cloud provider:

For AWS:

export AWS_ACCESS_KEY_ID=<your_aws_access_key>  # AWS authentication credential
export AWS_SECRET_ACCESS_KEY=<your_aws_secret_key>  # AWS authentication credential
export AWS_STATE_DYNAMODB_TABLE=<your_aws_dynamodb_table> # AWS DynamoDB table for Terraform state
export AWS_STATE_BUCKET=<your_aws_state_bucket> # AWS S3 bucket for Terraform state
export AWS_STATE_REGION=<aws_instance_region>  # AWS region for Terraform state # ex: us-west-2
export NGC_CLI_API_KEY=<your_ngc_key>  # NVIDIA GPU Cloud API key
export NVOC_SSH_PRIVATE_KEY_FILE=${HOME}/.ssh/id_rsa # SSH private key file
export NVOC_SSH_PUBLIC_KEY_FILE=${HOME}/.ssh/id_rsa.pub # SSH public key file
export LOCAL_CIDR=$(curl -s ifconfig.me) # Your public IP address (use: curl -s ifconfig.me)
export A2F_3D_CHART_VERSION=<Audio2Face-3D Helm chart version> # Audio2Face-3D Helm chart version

For Azure RESOURCE MANAGER(ARM):

export ARM_TENANT_ID=<your_tenant_id>  # Azure tenant identifier
export ARM_SUBSCRIPTION_ID=<your_subscription_id>  # Azure subscription identifier
export ARM_CLIENT_ID=<your_client_id>  # Azure service principal ID
export ARM_CLIENT_SECRET=<your_client_secret>  # Azure service principal secret
export ARM_RESOURCE_GRP_NAME=<your_arm_resource_group_name> # Azure resource group name
export ARM_STORAGE_ACCT_NAME=<your_arm_storage_account_name> # Azure storage account name
export ARM_CONTAINER_NAME=<your_arm_container_name> # Azure container name
export ARM_LOCATION=<your_arm_location> # Azure region for Terraform state # ex: westus
export NGC_CLI_API_KEY=<your_ngc_key>  # NVIDIA GPU Cloud API key
export NVOC_SSH_PRIVATE_KEY_FILE=${HOME}/.ssh/id_rsa # SSH private key file
export NVOC_SSH_PUBLIC_KEY_FILE=${HOME}/.ssh/id_rsa.pub # SSH public key file
export LOCAL_CIDR=$(curl -s ifconfig.me) # Your public IP address (use: curl -s ifconfig.me)
export A2F_3D_CHART_VERSION=<Audio2Face-3D Helm chart version> # Audio2Face-3D Helm chart version

6. Deploy#

Before deploying, you can remove any existing deployment with the same name:

./envbuild.sh uninstall -c all -f config.yml  # Removes existing deployment

Then run the deployment:

./envbuild.sh install -c all  # Starts the deployment process

The deployment will output access URLs and SSH commands upon completion, similar to:

===========================================================================================
access_urls:  # URLs for accessing different services
  app:
    grpc: http://<52.37.215.148>:30010/  # gRPC service endpoint
    nim: http://52.37.215.148:30020/  # NIM service endpoint
    prometheus: http://52.37.215.148:30030/  # Monitoring dashboard
ssh_command:  # Command to securely connect to the deployment
  app:
    master: ssh -i /home/nvidia/.ssh/id_rsa -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null ubuntu@52.37.215.148
===========================================================================================

7. Verify Deployment#

After deployment, verify that all components are running correctly.

SSH into the master node using the provided command:

ssh -i /home/nvidia/.ssh/id_rsa -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null ubuntu@52.37.215.148

Verify helm deployments:

helm ls --all-namespaces  # Lists all deployed applications

Expected output:

NAME                    NAMESPACE               REVISION        UPDATED                                 STATUS          CHART                          APP VERSION
audio2face3d-release    default                 1               2025-02-05 18:34:51.099874231 +0000 UTC deployed        audio2face-3d-1.3.15
gpu-operator-1738740177 nvidia-gpu-operator     1               2025-02-05 07:22:59.754174946 +0000 UTC deployed        gpu-operator-v24.6.2           v24.6.2
local-path-provisioner  default                 1               2025-02-05 07:26:25.849529634 +0000 UTC deployed        local-path-provisioner-0.0.31  v0.0.30

Check pod status:

kubectl get po  # Shows status of all running pods

Expected output:

NAME                                     READY   STATUS    RESTARTS   AGE
a2f-a2f-deployment-77ff75f956-2v7b8      1/1     Running   0          22m
dnsutils                                 1/1     Running   0          11h
local-path-provisioner-798c745db-qxrc2   1/1     Running   0          11h

For information on exposing the pod IP publicly, refer to the Kubernetes deployment documentation.

8. Uninstall#

When you need to remove the deployment, use the following command:

./envbuild.sh uninstall -c all -f config.yml  # Removes all deployed components