GitLab CI/CD Integration with Nutanix Blueprint

Last updated: March 4, 2026

---

Table of Contents

1. My Use Case for This Integration

2. How the Integration Works

3. Prism Central v3 API for Blueprint Operations

4. GitLab CI/CD Variable Setup

5. Blueprint Launch Script

6. GitLab Pipeline Design

7. Handling Application Outputs (VM IPs)

8. Environment Promotion with Blueprint Profiles

9. Teardown and Cleanup Automation

10. Full .gitlab-ci.yml Reference

11. Troubleshooting API Calls

---

My Use Case for This Integration

In my home-lab projects, I build small services that need a clean VM to test on. Rather than keeping a persistent "test VM" (which drifts over time), I wanted each GitLab pipeline run to:

1. Launch a fresh VM via a Nutanix Blueprint

2. Deploy the application to that VM

3. Run integration tests against it

4. Tear it down when done

The Blueprint in Nutanix handles the VM provisioning with all the baseline configuration (OS, network, user, SSH keys). GitLab CI/CD handles the application deployment and testing on top of it.

The connecting piece is the Prism Central v3 REST API.

---

How the Integration Works

Everything is driven through HTTP calls to Prism Central. No Nutanix-specific agent needs to run on the GitLab runner.

---

Prism Central v3 API for Blueprint Operations

Authentication

Prism Central's API uses HTTP Basic Auth. There is no token exchange needed for simple use — credentials go in every request header.

curl -sk \
  -u "${PC_USERNAME}:${PC_PASSWORD}" \
  -H "Content-Type: application/json" \
  "https://${PC_HOST}:9440/api/nutanix/v3/blueprints/list" \
  -d '{"kind": "blueprint"}'

Note: 9440 is the default Prism Central HTTPS port.

Find a Blueprint by Name

BLUEPRINT_UUID=$(curl -sk \
  -u "${PC_USERNAME}:${PC_PASSWORD}" \
  -H "Content-Type: application/json" \
  -X POST \
  "https://${PC_HOST}:9440/api/nutanix/v3/blueprints/list" \
  -d '{"kind": "blueprint", "filter": "name==my-app-blueprint"}' \
  | jq -r '.entities[0].metadata.uuid')
echo "Blueprint UUID: $BLUEPRINT_UUID"

Get Blueprint Runtime Editables

Before launching, you need the blueprint's runtime variable spec, which tells you which variables you can override at launch time:

curl -sk \
  -u "${PC_USERNAME}:${PC_PASSWORD}" \
  "https://${PC_HOST}:9440/api/nutanix/v3/blueprints/${BLUEPRINT_UUID}/runtime_editables" \
  | jq .

Launch a Blueprint

LAUNCH_RESPONSE=$(curl -sk \
  -u "${PC_USERNAME}:${PC_PASSWORD}" \
  -H "Content-Type: application/json" \
  -X POST \
  "https://${PC_HOST}:9440/api/nutanix/v3/blueprints/${BLUEPRINT_UUID}/launch" \
  -d '{
    "spec": {
      "app_name": "my-app-ci-'${CI_PIPELINE_ID}'",
      "app_description": "Deployed by GitLab pipeline '${CI_PIPELINE_ID}'",
      "app_profile_reference": {
        "kind": "app_profile",
        "uuid": "'${PROFILE_UUID}'"
      },
      "runtime_editables": {
        "variable_list": [
          {
            "name": "APP_REPO_URL",
            "value": "'${CI_PROJECT_URL}'"
          }
        ]
      }
    }
  }')

APP_UUID=$(echo "$LAUNCH_RESPONSE" | jq -r '.status.application_uuid')
REQUEST_ID=$(echo "$LAUNCH_RESPONSE" | jq -r '.request_id')
echo "App UUID: $APP_UUID"
echo "Request ID: $REQUEST_ID"

Poll for Completion

Blueprint launches are asynchronous. Poll the application state until it reaches running or error:

wait_for_app() {
  local APP_UUID=$1
  local MAX_RETRIES=30
  local SLEEP=20

  for i in $(seq 1 $MAX_RETRIES); do
    STATE=$(curl -sk \
      -u "${PC_USERNAME}:${PC_PASSWORD}" \
      "https://${PC_HOST}:9440/api/nutanix/v3/apps/${APP_UUID}" \
      | jq -r '.status.state')

    echo "[$i/$MAX_RETRIES] Application state: $STATE"

    if [[ "$STATE" == "running" ]]; then
      echo "Application is ready."
      return 0
    elif [[ "$STATE" == "error" ]]; then
      echo "Application failed to deploy!"
      return 1
    fi

    sleep $SLEEP
  done

  echo "Timeout waiting for application to reach running state"
  return 1
}

Get VM IP Address

Once the application state is running, retrieve the VM's IP address:

VM_IP=$(curl -sk \
  -u "${PC_USERNAME}:${PC_PASSWORD}" \
  "https://${PC_HOST}:9440/api/nutanix/v3/apps/${APP_UUID}" \
  | jq -r '.status.resources.deployment_list[0].substrate_configuration.element_list[0].address')
echo "VM IP: $VM_IP"

The JSON path varies depending on your blueprint structure. I recommend running jq . on a launched application first to explore the structure and find the right path.

Delete an Application

curl -sk \
  -u "${PC_USERNAME}:${PC_PASSWORD}" \
  -X DELETE \
  "https://${PC_HOST}:9440/api/nutanix/v3/apps/${APP_UUID}"

---

GitLab CI/CD Variable Setup

Store sensitive values in GitLab CI/CD Variables (Project → Settings → CI/CD → Variables). Never hardcode credentials in .gitlab-ci.yml.

Variable Name	Type	Description
PC_HOST	Variable	Prism Central FQDN or IP
PC_USERNAME	Variable	Prism Central username
PC_PASSWORD	Secret	Prism Central password (masked + protected)
BLUEPRINT_NAME	Variable	Name of the blueprint to launch
BLUEPRINT_PROFILE_DEV	Variable	UUID of the "dev" profile
BLUEPRINT_PROFILE_PROD	Variable	UUID of the "prod" profile

Get profile UUIDs from Prism Central UI (Blueprint Designer → Profiles → click profile → UUID in URL) or via API:

curl -sk \
  -u "${PC_USERNAME}:${PC_PASSWORD}" \
  "https://${PC_HOST}:9440/api/nutanix/v3/blueprints/${BLUEPRINT_UUID}" \
  | jq '.spec.resources.app_profile_list[] | {name: .name, uuid: .uuid}'

---

Blueprint Launch Script

I maintain a reusable shell script in my project repo (scripts/nutanix_deploy.sh) that the pipeline calls:

#!/usr/bin/env bash
# scripts/nutanix_deploy.sh
# Usage: ./nutanix_deploy.sh <blueprint_name> <profile_uuid> <app_name>
set -euo pipefail

BLUEPRINT_NAME="${1}"
PROFILE_UUID="${2}"
APP_NAME="${3}"
STATE_FILE="${4:-.nutanix_app_state}"

PC_BASE="https://${PC_HOST}:9440/api/nutanix/v3"
AUTH="${PC_USERNAME}:${PC_PASSWORD}"

# ---- Find blueprint UUID ----
echo "[nutanix] Looking up blueprint: $BLUEPRINT_NAME"
BLUEPRINT_UUID=$(curl -sk \
  -u "$AUTH" \
  -H "Content-Type: application/json" \
  -X POST "${PC_BASE}/blueprints/list" \
  -d "{\"kind\": \"blueprint\", \"filter\": \"name==${BLUEPRINT_NAME}\"}" \
  | jq -r '.entities[0].metadata.uuid')

if [[ -z "$BLUEPRINT_UUID" || "$BLUEPRINT_UUID" == "null" ]]; then
  echo "[ERROR] Blueprint '$BLUEPRINT_NAME' not found in Prism Central"
  exit 1
fi
echo "[nutanix] Blueprint UUID: $BLUEPRINT_UUID"

# ---- Launch blueprint ----
echo "[nutanix] Launching application: $APP_NAME"
LAUNCH_RESPONSE=$(curl -sk \
  -u "$AUTH" \
  -H "Content-Type: application/json" \
  -X POST "${PC_BASE}/blueprints/${BLUEPRINT_UUID}/launch" \
  -d "{
    \"spec\": {
      \"app_name\": \"${APP_NAME}\",
      \"app_description\": \"GitLab CI pipeline ${CI_PIPELINE_ID:-manual}\",
      \"app_profile_reference\": {
        \"kind\": \"app_profile\",
        \"uuid\": \"${PROFILE_UUID}\"
      }
    }
  }")

APP_UUID=$(echo "$LAUNCH_RESPONSE" | jq -r '.status.application_uuid')
if [[ -z "$APP_UUID" || "$APP_UUID" == "null" ]]; then
  echo "[ERROR] Failed to launch blueprint. Response:"
  echo "$LAUNCH_RESPONSE" | jq .
  exit 1
fi
echo "[nutanix] Application UUID: $APP_UUID"
echo "$APP_UUID" > "$STATE_FILE"

# ---- Wait for running state ----
MAX_RETRIES=40
SLEEP_SEC=15
for i in $(seq 1 $MAX_RETRIES); do
  STATE=$(curl -sk \
    -u "$AUTH" \
    "${PC_BASE}/apps/${APP_UUID}" \
    | jq -r '.status.state')
  echo "[nutanix] [$i/$MAX_RETRIES] State: $STATE"

  [[ "$STATE" == "running" ]] && { echo "[nutanix] Application is running."; break; }
  [[ "$STATE" == "error" ]] && { echo "[ERROR] Application failed."; exit 1; }
  [[ $i -eq $MAX_RETRIES ]] && { echo "[ERROR] Timeout waiting for running state."; exit 1; }
  sleep $SLEEP_SEC
done

# ---- Extract VM IP ----
VM_IP=$(curl -sk \
  -u "$AUTH" \
  "${PC_BASE}/apps/${APP_UUID}" \
  | jq -r '.status.resources.deployment_list[0].substrate_configuration.element_list[0].address')
echo "[nutanix] VM IP: $VM_IP"

# ---- Export state for downstream jobs ----
cat > nutanix.env <<EOF
NUTANIX_APP_UUID=${APP_UUID}
NUTANIX_VM_IP=${VM_IP}
EOF
echo "[nutanix] State written to nutanix.env"

And a corresponding teardown script (scripts/nutanix_destroy.sh):

#!/usr/bin/env bash
# scripts/nutanix_destroy.sh
# Usage: ./nutanix_destroy.sh <app_uuid>
set -euo pipefail

APP_UUID="${1}"
PC_BASE="https://${PC_HOST}:9440/api/nutanix/v3"
AUTH="${PC_USERNAME}:${PC_PASSWORD}"

echo "[nutanix] Deleting application: $APP_UUID"
RESPONSE=$(curl -sk \
  -u "$AUTH" \
  -X DELETE \
  "${PC_BASE}/apps/${APP_UUID}")

echo "$RESPONSE" | jq -r '.description // "Delete request submitted"'

# Wait for deletion
for i in $(seq 1 20); do
  HTTP_CODE=$(curl -sk -o /dev/null -w "%{http_code}" \
    -u "$AUTH" \
    "${PC_BASE}/apps/${APP_UUID}")
  [[ "$HTTP_CODE" == "404" ]] && { echo "[nutanix] Application deleted."; exit 0; }
  echo "[nutanix] Waiting for deletion... ($i/20)"
  sleep 15
done

echo "[WARN] Application may not have been fully deleted — check Prism Central"

---

GitLab Pipeline Design

The pipeline has three stages:

1. provision — launch the Blueprint and capture the VM IP

2. deploy_and_test — deploy the app, run tests (uses VM IP from stage 1)

3. teardown — destroy the application (always runs, even on failure)

Passing State Between Jobs

GitLab jobs run in separate containers. To pass the APP_UUID and VM_IP between jobs, I use artifacts:

provision:
  stage: provision
  script:
    - bash scripts/nutanix_deploy.sh "$BLUEPRINT_NAME" "$BLUEPRINT_PROFILE_DEV" "my-app-ci-${CI_PIPELINE_ID}"
  artifacts:
    reports:
      dotenv: nutanix.env   # makes NUTANIX_APP_UUID and NUTANIX_VM_IP available to downstream jobs
    paths:
      - nutanix.env
    expire_in: 1 hour

The dotenv artifact type automatically injects the variables into subsequent jobs.

---

Full .gitlab-ci.yml Reference

# .gitlab-ci.yml

stages:
  - provision
  - deploy_and_test
  - teardown

variables:
  BLUEPRINT_NAME: "my-app-blueprint"

# ---- Stage 1: Provision fresh VM from Blueprint ----
provision:
  stage: provision
  image: alpine:3.19
  before_script:
    - apk add --no-cache curl jq bash
  script:
    - bash scripts/nutanix_deploy.sh
        "$BLUEPRINT_NAME"
        "$BLUEPRINT_PROFILE_DEV"
        "my-app-ci-${CI_PIPELINE_ID}"
  artifacts:
    reports:
      dotenv: nutanix.env
    paths:
      - nutanix.env
    expire_in: 1 hour
  rules:
    - if: '$CI_PIPELINE_SOURCE == "push"'

# ---- Stage 2: Deploy application and run tests ----
deploy_and_test:
  stage: deploy_and_test
  image: alpine:3.19
  dependencies:
    - provision
  before_script:
    - apk add --no-cache openssh-client rsync
    - mkdir -p ~/.ssh
    - echo "$DEPLOY_SSH_KEY" > ~/.ssh/id_rsa
    - chmod 600 ~/.ssh/id_rsa
    - ssh-keyscan -H "$NUTANIX_VM_IP" >> ~/.ssh/known_hosts 2>/dev/null
  script:
    - echo "Deploying to VM at $NUTANIX_VM_IP"
    # Copy application code to VM
    - rsync -az --exclude=".git" ./ ubuntu@${NUTANIX_VM_IP}:/opt/myapp/
    # Run setup on the VM
    - ssh ubuntu@${NUTANIX_VM_IP} "cd /opt/myapp && pip3 install -r requirements.txt && systemctl restart myapp"
    # Run tests pointing to the fresh VM
    - ssh ubuntu@${NUTANIX_VM_IP} "cd /opt/myapp && python3 -m pytest tests/integration/ -v"
  rules:
    - if: '$CI_PIPELINE_SOURCE == "push"'

# ---- Stage 3: Teardown (always runs) ----
teardown:
  stage: teardown
  image: alpine:3.19
  dependencies:
    - provision
  before_script:
    - apk add --no-cache curl jq bash
  script:
    - |
      if [[ -n "$NUTANIX_APP_UUID" ]]; then
        bash scripts/nutanix_destroy.sh "$NUTANIX_APP_UUID"
      else
        echo "No NUTANIX_APP_UUID found, skipping teardown"
      fi
  when: always  # runs even if previous stages fail
  rules:
    - if: '$CI_PIPELINE_SOURCE == "push"'

---

Environment Promotion with Blueprint Profiles

A single Blueprint can carry multiple profiles. I keep:

• dev profile: Minimum vCPU and memory — fast to spin up, used for integration test pipelines

• staging profile: Same sizing as production — used for pre-release pipelines on main branch

In .gitlab-ci.yml, I select the profile based on the branch:

provision:
  stage: provision
  script:
    - |
      if [[ "$CI_COMMIT_BRANCH" == "main" ]]; then
        PROFILE_UUID="$BLUEPRINT_PROFILE_STAGING"
      else
        PROFILE_UUID="$BLUEPRINT_PROFILE_DEV"
      fi
      bash scripts/nutanix_deploy.sh "$BLUEPRINT_NAME" "$PROFILE_UUID" "my-app-ci-${CI_PIPELINE_ID}"

This keeps all infrastructure variation inside the Blueprint profiles, not scattered across pipeline scripts.

---

Teardown and Cleanup Automation

One problem I ran into: if a pipeline fails partway through and GitLab variables are not available (e.g., the pipeline itself was cancelled before teardown), stale VMs accumulate on the cluster.

My housekeeping approach: a scheduled GitLab pipeline runs nightly to find and delete any applications with the ci- prefix that are older than 6 hours:

#!/usr/bin/env bash
# scripts/nutanix_cleanup_stale.sh
set -euo pipefail

PC_BASE="https://${PC_HOST}:9440/api/nutanix/v3"
AUTH="${PC_USERNAME}:${PC_PASSWORD}"
MAX_AGE_HOURS=6

# List all running applications with "my-app-ci-" prefix
APPS=$(curl -sk \
  -u "$AUTH" \
  -H "Content-Type: application/json" \
  -X POST "${PC_BASE}/apps/list" \
  -d '{"kind": "app", "length": 100}' \
  | jq -r '.entities[] | select(.metadata.name | startswith("my-app-ci-")) | {uuid: .metadata.uuid, name: .metadata.name, created: .metadata.creation_time}')

NOW=$(date +%s)
while IFS= read -r APP; do
  UUID=$(echo "$APP" | jq -r '.uuid')
  NAME=$(echo "$APP" | jq -r '.name')
  CREATED=$(echo "$APP" | jq -r '.created')
  CREATED_SEC=$(date -d "$CREATED" +%s 2>/dev/null || gdate -d "$CREATED" +%s)
  AGE_HOURS=$(( (NOW - CREATED_SEC) / 3600 ))

  if [[ $AGE_HOURS -gt $MAX_AGE_HOURS ]]; then
    echo "Deleting stale app: $NAME (age: ${AGE_HOURS}h)"
    curl -sk -u "$AUTH" -X DELETE "${PC_BASE}/apps/${UUID}" | jq -r '.description // "submitted"'
  else
    echo "Keeping: $NAME (age: ${AGE_HOURS}h)"
  fi
done <<< "$APPS"

This runs as a scheduled pipeline in GitLab (Settings → CI/CD → Schedules → nightly).

---

Troubleshooting API Calls

Problem: SSL certificate errors Nutanix CE ships with a self-signed certificate. Add -k (insecure) or --insecure to curl in lab environments. In production, import the proper certificate.

Problem: 401 Unauthorized Verify username and password are correct. The account needs at least "Operator" role on the Prism Central project that owns the blueprint.

Problem: Blueprint UUID is null The filter parameter is case-sensitive and uses a specific syntax. Check that the blueprint name in the API filter matches exactly what's in Prism Central.

# Debug: list all blueprints and check names
curl -sk \
  -u "${PC_USERNAME}:${PC_PASSWORD}" \
  -H "Content-Type: application/json" \
  -X POST "https://${PC_HOST}:9440/api/nutanix/v3/blueprints/list" \
  -d '{"kind": "blueprint", "length": 50}' \
  | jq -r '.entities[].metadata.name'

Problem: Application stays in "provisioning" state forever Check the blueprint launch logs in Prism Central (Self-Service → Applications → click the app → Audit tab). Usually this means a Task script failed or the VM image is missing.

Problem: VM IP is null after app reaches "running" The JSON path to the IP depends on the blueprint substrate type and whether IPAM is configured. Inspect the full app response with | jq . to find the right path.

---

Next Steps

Continue to the next article: Automating Nutanix Backup with Ansible — where I cover using the nutanix.ncp Ansible collection to automate VM snapshots and protection domains.