rest-api

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 Core services to be available.

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 the latest OpenAPI schema in the REST API Reference.

Prerequisites

• Go 1.27.3 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

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:

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 Core services. Uses helm-prereqs/setup.sh, 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=<pull-secret-or-api-key>
export NICO_IMAGE_REGISTRY=my-registry.example.com/nico
export NICO_CORE_IMAGE_TAG=<nico-core-tag>    # NVIDIA Infrastructure Controller Core image tag
export NICO_REST_IMAGE_TAG=v1.0.4               # NICo REST image tag

# 4. Run setup
cd ../helm-prereqs
./setup.sh -y     # or ./setup.sh for interactive prompts

To tear everything down:

./clean.sh

See 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 for a concise bring-up guide, and Detailed Installation Guide 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 for configuration, authentication, shell completion, and the full command reference.

Using the API

Get an Access Token

TOKEN=$(curl -s -X POST "http://localhost:8082/realms/nico-dev/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=nico-api" \
  -d "client_secret=nico-local-secret" \
  -d "grant_type=password" \
  -d "username=admin@example.com" \
  -d "password=adminpassword" | jq -r .access_token)

Example API Requests

# Health check
curl -s http://localhost:8388/healthz -H "Authorization: Bearer $TOKEN" | jq .

# Get current tenant (auto-creates on first access)
curl -s "http://localhost:8388/v2/org/test-org/nico/tenant/current" \
  -H "Authorization: Bearer $TOKEN" | jq .

# List sites
curl -s "http://localhost:8388/v2/org/test-org/nico/site" \
  -H "Authorization: Bearer $TOKEN" | jq .

Test Users

All users have the test-org organization assigned.

Building Docker Images

Build All Images

make docker-build

Images are tagged with localhost:5000 registry and latest tag by default.

Build with Custom Registry and Tag

make docker-build IMAGE_REGISTRY=my-registry.example.com/nico IMAGE_TAG=v1.0.0

Push to Your Registry

1. Authenticate with your registry:

# Docker Hub
docker login

# AWS ECR
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 123456789.dkr.ecr.us-east-1.amazonaws.com

# Google Container Registry
gcloud auth configure-docker

# Azure Container Registry
az acr login --name myregistry

1. Build and push:

REGISTRY=my-registry.example.com/infra-controller
TAG=v1.0.0

make docker-build IMAGE_REGISTRY=$REGISTRY IMAGE_TAG=$TAG

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 "$REGISTRY/$image:$TAG"
done

Available Images

Architecture

Supporting modules:

• common - Shared utilities and configurations
• auth - Authentication and authorization
• ipam - IP Address Management

OpenAPI Schema Development

OpenAPI schema must be updated whenever the API endpoints are added/updated. Please view instructions at OpenAPI README

Secret Scanning

The repository root's pre-commit hook scans REST changes for secrets too. See Secret Scanning for setup.

Release Notice

The software is provided "as is" without warranties of any kind. Features, APIs, and configurations may change in future releases. For production deployments, please test thoroughly in non-critical environments first.

License

NICo REST is licensed under the Apache License 2.0. Licenses for the vendored go-ipam (ipam/) and Temporal Helm chart (temporal-helm/) are in THIRD-PARTY-LICENSES. This project will download and install additional third-party open source software projects. Review the license terms of these open source projects before use.