Skip to content

First Steps

This guide walks you through configuring Cisco Intersight using Network as Code, starting with a pool and a policy in two YAML files and a short Terraform module block. It then adds a server profile template and a server, which are the building blocks for provisioning UCS servers at scale.

Prerequisites:

  • Terraform 1.8.0 or later
  • Your preferred text editor / IDE (such as Visual Studio Code)
  • An Intersight account (SaaS or appliance) with permission to create an API key. A v3 key is recommended
  • An existing Intersight organization. The built-in default organization works for this guide
  1. In Intersight, go to Settings → API Keys and generate a new API key. Save the API Key ID and download the Secret Key file. The secret key is only shown once.

  2. The Compute module authenticates using environment variables. Set the following in your terminal:

    Terminal window
    export INTERSIGHT_API_KEY=<api-key-id>
    export INTERSIGHT_SECRET_KEY=~/intersight/SecretKey.txt
    export INTERSIGHT_ENDPOINT_URL=https://intersight.com

    INTERSIGHT_SECRET_KEY can be either the path to the secret key file or the key content itself. Set INTERSIGHT_ENDPOINT_URL to the URL of your Intersight region (for example https://eu-central-1.intersight.com) or of your appliance.

  3. In a new project directory, create a data directory. In it, create a file named organizations.nac.yaml that declares the organization the objects go into:

    ---
    compute:
    intersight:
    organizations:
    - name: default
    managed: false

    managed: false tells the module that the organization already exists, so it only looks it up. The built-in default organization must always be set to managed: false.

    Next, create pools.nac.yaml with an IP pool:

    ---
    compute:
    intersight:
    organizations:
    - name: default
    pools:
    ip:
    - name: management_ip
    description: In-band management IP pool
    ipv4_config:
    gateway: 10.0.0.1
    netmask: 255.255.255.0
    primary_dns: 10.0.0.10
    ipv4_blocks:
    - from: 10.0.0.50
    size: 100

    Then create policies.nac.yaml with an NTP policy:

    ---
    compute:
    intersight:
    organizations:
    - name: default
    policies:
    ntp:
    - name: ntp
    description: NTP policy with dual NTP servers
    enabled: true
    timezone: America/New_York
    ntp_servers:
    - ntp1.example.com
    - ntp2.example.com

    The pool and the policy are created in the default organization. The module merges all files in the data directory, so you can split the configuration across as many files as you like.

  4. In the project directory, create a file named main.tf:

    module "compute" {
    source = "netascode/nac-compute/intersight"
    version = "0.2.0"
    yaml_directories = ["data"]
    manage_intersight_pools = true
    manage_intersight_policies = true
    }

    This is the only Terraform configuration required. The nac-compute module reads the YAML files and maps their contents to the underlying Intersight provider resources automatically.

  5. Run the following command to download the provider and module:

    Terminal window
    terraform init
  6. Preview and apply your changes:

    Terminal window
    terraform apply

    Review the plan and type yes to confirm. Terraform creates the IP pool and the NTP policy in the default organization.

Congratulations! You have configured your first Intersight objects using Network as Code. The sections below show how to build on them with a server profile template and servers.

A server profile template bundles pools and policies into a reusable server configuration. Templates, pools and policies reference each other by name.

First, add an IMC access policy to policies.nac.yaml. It takes its in-band management addresses from the management_ip pool:

---
compute:
intersight:
organizations:
- name: default
policies:
imc_access:
- name: imc_access
description: IMC access policy for in-band management on VLAN 10
configure_inband: true
configure_out_of_band: false
inband_vlan: 10
ipv4: true
ipv6: false
inband_ip_pool: management_ip
ntp:
- name: ntp
description: NTP policy with dual NTP servers
enabled: true
timezone: America/New_York
ntp_servers:
- ntp1.example.com
- ntp2.example.com

Then create templates.nac.yaml with a server profile template that uses the IMC access policy:

---
compute:
intersight:
organizations:
- name: default
templates:
server:
- name: esxi_server
description: Server template for FI-attached VMware ESXi hosts
target_platform: FIAttached
imc_access_policy: imc_access

target_platform is FIAttached for servers connected to fabric interconnects, or Standalone for rack servers managed directly by Intersight. Not every policy applies to every platform: the NTP policy, for example, is not supported on FIAttached server profiles, where NTP is set in the domain profile instead. It is used by Standalone server profiles and by domain templates. Add manage_intersight_templates = true to the module block in main.tf and run terraform apply.

Servers are defined in the top-level servers list, outside the organizations. Each server gets a server profile derived from its profile_template. Create servers.nac.yaml:

---
compute:
servers:
- name: esxi_host_01
provisioning:
managed_by: intersight
profile_template: esxi_server
action: deploy
intersight:
organization: default
serial_number: FCH12345678

The serial_number assigns the profile to the hardware. The server does not need to be inventoried in Intersight yet: the profile is pre-assigned and attaches to the server once Intersight claims it. Leave the serial number out to create an unassigned profile.

The action attribute controls what happens to the profile:

  • none (default): create the profile and assign it, without deploying
  • sync: sync the profile with its template
  • deploy: deploy the profile to the server, which also activates changes that need a reboot
  • sync_and_deploy: sync with the template, then deploy
  • unassign: detach the profile from the hardware

A deploy only runs when the profile is created, its template changes or action is changed to deploy, not on every apply. Add manage_servers = true to the module block in main.tf and run terraform apply.

A server can replace some of its template’s policies under provisioning.intersight.policies. For example, to give one host a different IMC access policy (here imc_access_lab, a second IMC access policy you define in policies.nac.yaml):

---
compute:
servers:
- name: esxi_host_02
provisioning:
managed_by: intersight
profile_template: esxi_server
intersight:
organization: default
serial_number: FCH87654321
policies:
imc_access_policy: imc_access_lab

Intersight does not allow a profile derived from a template to differ from it. A server with overrides therefore gets a standalone profile: its policies are the template’s, with the server’s settings replacing them. This avoids a dedicated template for every server that differs slightly from the others.

In larger environments, different teams or pipelines can own different parts of the configuration. The manage_* flags enable whole categories in a workspace, and the managed_* lists narrow them down by name or tag. For example, a workspace for the pools and policies of two organizations:

module "compute" {
source = "netascode/nac-compute/intersight"
version = "0.2.0"
yaml_directories = ["data"]
manage_intersight_pools = true
manage_intersight_policies = true
managed_intersight_organizations = ["dc-a-prod", "dc-a-dev"]
}

And a separate workspace that only manages the servers of one cluster, selected by tag:

module "compute" {
source = "netascode/nac-compute/intersight"
version = "0.2.0"
yaml_directories = ["data"]
manage_servers = true
managed_server_tags = ["cluster=vsphere-prod-01"]
}

An object is included when its name is in the name list or it carries all the listed tags. Empty lists include everything. Domain and chassis profiles are managed with manage_intersight_profiles.


You now have the building blocks of a Network as Code Compute deployment. Explore the Compute Data Models section for the complete list of configurable attributes.