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 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 "nvidia/nim/audio2face-3d-nv-one-click-script:1.3.10"
The folder contains deployment packages for both AWS and Azure cloud platforms:
deploy-audio2face3d-aws-cns.tar.gz
- Package for AWS deploymentdeploy-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.2.0
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