NVIDIA/infra-controller-rest

NVIDIA/infra-controller-rest

Description: NVIDIA Infra Controller - Hardware Lifecycle Management (REST API)

Language: Go

License: Apache-2.0

Stars: 38

Forks: 38

Open issues: 7

Created: 2025-11-05T22:24:33Z

Pushed: 2026-06-02T04:30:02Z

Default branch: main

Fork: no

Archived: yes

README:

NVIDIA Infrastructure Controller (NICo) REST API

A collection of microservices that comprise the management backend for NVIDIA Infrastructure Controller (NICo), exposed as a REST API.

In deployments, NVIDIA Infrastructure Controller REST requires NVIDIA Infrastructure Controller Core to function.

The REST layer can be deployed in the datacenter with NVIDIA Infrastructure Controller Core, or deployed anywhere in Cloud and allow Site Agent to connect from the datacenter. Multiple NVIDIA Infrastructure Controller Cores running in different datacenters can also connect to NVIDIA Infrastructure Controller REST through respective Site Agents.

View latest OpenAPI schema on GitHub pages.

> [!IMPORTANT] > To ensure a unified entry point to the NVIDIA Infra Controller, the REST API repo is being merged into the infra-controller repo under rest-api directory. This transition will be completed on June 2nd, 2026.

Prerequisites

• Go 1.25.4 or later
• Docker 20.10+ with BuildKit enabled
• Make
• Kind (for local deployment)
• kubectl (for local deployment)
• jq (optional, for parsing JSON responses)

Core Compatibility Matrix

| NICo REST Version | NICo Core Version | |------------------|------------------| | v1.6.x | v0.10.x | | v1.5.x | v0.9.x | | v1.4.x | v0.8.x | | v1.3.x | v0.7.x |

Versions older than v1.3.0 are no longer supported.

Quick Start

Run Unit Tests

make test

Tests require PostgreSQL. The Makefile automatically manages a test container.

Test database configuration:

• Host: localhost
• Port: 30432
• User/Password: postgres / postgres

Option A: Local Development with Kind

The fastest path to a running stack on your laptop. Builds images locally, spins up a Kind cluster, and deploys a mock NVIDIA Infrastructure Controller Core automatically — no external registry or bare-metal cluster required.

make kind-reset

This deploys the full stack via Helm charts (default). It: 1. Creates a Kind Kubernetes cluster 2. Builds all Docker images 3. Sets up infrastructure (PostgreSQL, Temporal, Keycloak, cert-manager, etc.) 4. Deploys app services via Helm umbrella chart 5. Bootstraps and deploys site-agent 6. Deploys a mock NVIDIA Infrastructure Controller Core

To deploy via Kustomize overlays instead:

make kind-reset-kustomize

Once complete, services are available at:

| Service | URL | |---------|-----| | API | http://localhost:8388 | | Keycloak | http://localhost:8082 | | Temporal UI | http://localhost:8233 | | Adminer (DB UI) | http://localhost:8081 |

Other useful commands:

make kind-status # Check pod status
make kind-logs # Tail API logs
make kind-redeploy # Rebuild and restart after code changes (Kustomize)
make helm-redeploy # Rebuild and restart after code changes (Helm)
make kind-verify # Run health checks
make helm-verify # Check Helm deployment rollout status
make helm-uninstall # Uninstall Helm releases
make kind-down # Tear down cluster

Option B: Bare-Metal Cluster with helm-prereqs

For deploying onto a real Kubernetes cluster alongside NVIDIA Infrastructure Controller Core. Uses helm-prereqs/setup.sh from the infra-controller-core repo, which installs the full prerequisite stack (cert-manager, Vault, external-secrets, PostgreSQL, Temporal, Keycloak) and deploys both NICo Core and NICo REST in the correct order.

# 1. Build and push images to your registry
make docker-build IMAGE_REGISTRY=my-registry.example.com/nico IMAGE_TAG=v1.0.4

for image in nico-rest-api nico-rest-workflow nico-rest-site-manager \
nico-rest-site-agent nico-rest-db nico-rest-cert-manager; do
docker push my-registry.example.com/nico/$image:v1.0.4
done

# 2. Set environment variables
export KUBECONFIG=/path/to/kubeconfig
export REGISTRY_PULL_SECRET=
export NICO_IMAGE_REGISTRY=my-registry.example.com/nico
export NICO_CORE_IMAGE_TAG= # NVIDIA Infrastructure Controller Core image tag
export NICO_REST_IMAGE_TAG=v1.0.4 # NICo REST image tag

# 3. Clone infra-controller-core (if not already present as a sibling directory)
git clone https://github.com/NVIDIA/infra-controller-core.git ../infra-controller-core

# 4. Run setup from the infra-controller-core repo
cd ../infra-controller-core/helm-prereqs
./setup.sh -y # or ./setup.sh for interactive prompts

The setup script auto-detects this repo from the sibling path infra-controller-rest. Set NICO_REPO=/path/to/this/repo to override.

To tear everything down:

./clean.sh

See infra-controller-core/helm-prereqs/README.md for the full reference: PKI architecture, phase-by-phase description, site customization, secrets reference, and troubleshooting (including site-agent gRPC connectivity).

Option C: Manual / Kustomize Production Deployment

See [Deployment QuickStart Guide](deploy/README.md) for a concise bring-up guide, and [Detailed Installation Guide](deploy/INSTALLATION.md) for the full step-by-step reference with per-component explanations.

CLI

nicocli is a command-line client that wraps the full REST API. Install it and set up configs for each environment you work with:

make nico-cli # build and install to $GOPATH/bin
nicocli init # generate ~/.nico/config.yaml

Create a config per environment (~/.nico/config.yaml, ~/.nico/config.staging.yaml, ~/.nico/config.prod.yaml), then launch the interactive TUI which handles environment selection, login, and token refresh automatically:

nicocli tui

All commands are also available directly for scripting and one-off use:

nicocli --config ~/.nico/config.staging.yaml site list

See [cli/README.md](cli/README.md) for configuration, authentication, shell completion, and the full command reference.

Using the...