Task 13 - Run a CI/CD pipeline

Estimated Time to Complete: ~20 minutes

terraform state list

Up until now you've been driving Terraform manually: init, plan, apply. That's fine for learning, but production teams run the same workflow through CI/CD so every change is validated, previewed, applied, and tested the same way - without a human typing commands. In this task you'll do exactly that using a pre-configured GitLab pipeline.

What you'll learn

By the end of this task you will have:

• Navigated the netascode/nac-iosxe-terraform GitLab project and read its .gitlab-ci.yml
• Committed a change via the GitLab Web IDE and watched the pipeline trigger automatically
• Observed a complete pipeline run (validate → plan → deploy → notify) and verified the deployed change on the lab devices

CI/CD for Network as Code

The lab ships with a pre-configured GitLab repository containing your Network as Code project and a ready-to-run CI/CD pipeline. Every push or merge request triggers a pipeline that runs the same five stages you just performed by hand - plus a few you didn't:

Two important behaviors to notice before we run one:

• Merge-request pipelines only preview - they run validate + plan and post the plan diff as an MR comment. They never touch the devices. This is the guardrail that makes code review meaningful.
• Main-branch pipelines actually deploy - they run all five stages (validate → plan → deploy → test → notify). Merging to main is the act that commits a change to the real network.

Same pipeline definition, different behavior per branch - a simple pattern that gives you a preview environment for free.

Step 1: Access GitLab

In Chrome, navigate to GitLab - open the following link in a new tab:

https://198.18.133.101

If prompted, log in with credentials: Username: root / Password: C1sco12345

Step 2: Navigate to the NaC-IOSXE project

After logging in, you'll see the GitLab dashboard. Click on the netascode/nac-iosxe-terraform project to open it.

The project page shows your repository files, including:

• data/ folder with your YAML configurations - Same as you created in Task 02
• tests/ folder with your ROBOT tests - Same as the ACL tests from optional Task 11
• main.tf - Terraform configuration - Same as you created in Task 02
• .schema.yaml - The Network as Code for IOS XE schema - Same as you used in Task 10
• .gitlab-ci.yml - CI/CD pipeline definition file - This is new!

CI/CD pipeline configuration

Before running the pipeline, understand how it's configured first. Click on .gitlab-ci.yml to view the pipeline definition:

A CI/CD pipeline is an automated workflow of tasks that enables changes to be deployed in a consistent and repeatable manner. This lab leverages pipelines to automate the tasks you previously performed manually. This pipeline example includes the following stages: validate, plan, deploy, and notify.

image: danischm/nac:0.1.6
stages:
  - validate
  - plan
  - deploy
  - notify

variables:
  IOSXE_USERNAME:
    description: "Cisco IOS XE Username"
  IOSXE_PASSWORD:
    description: "Cisco IOS XE Password"
  # ... additional variables for GitLab tokens, Terraform state, Webex notifications ...

cache:
  key: terraform_modules_and_lock
  paths:
    - .terraform
    - .terraform.lock.hcl
    - defaults.yaml
    - model.yaml

validate:
  stage: validate
  script:
    - set -o pipefail && terraform fmt -check |& tee fmt_output.txt
    - set -o pipefail && nac-validate ./data/ |& tee validate_output.txt
  # ... artifacts and rules configuration ...

plan:
  stage: plan
  script:
    - terraform init -upgrade -input=false
    - terraform plan -out=plan.tfplan -input=false
    - terraform show -no-color plan.tfplan > plan.txt
    # ... additional plan output processing ...
  # ... artifacts, dependencies, and branch rules ...

deploy:
  stage: deploy
  script:
    - terraform init -input=false
    - terraform apply -input=false -auto-approve plan.tfplan
  # ... runs only on main branch ...

failure:
  stage: notify
  script:
    - python3 .ci/webex-notification-gitlab.py -f
  when: on_failure

success:
  stage: notify
  script:
    - python3 .ci/webex-notification-gitlab.py -s
  when: on_success

Key concepts:

• image - Uses a pre-built Docker container with Terraform, nac-validate, and other tools
• stages - Define the order of execution (validate → plan → deploy → notify)
• variables - Pipeline variables for credentials (IOS XE, GitLab), entered at runtime
• cache - Preserves Terraform modules and state between pipeline runs
• validate - Runs terraform fmt check and nac-validate schema validation
• plan - Creates the Terraform execution plan and generates reports
• deploy - Applies the configuration automatically (runs on main branch only)
• failure/success - Send Webex notifications based on pipeline outcome

View existing pipelines

To see the pipeline history, navigate to Build → Pipelines in the left sidebar.

You'll see a list of past pipeline runs with their status (passed, failed, running).

State file management

Navigate to Home (GitLab icon in the top left), select netascode/nac-iosxe-terraform, then open the main.tf file.

The pipeline uses GitLab's http backend to store the Terraform state file on the GitLab server. This allows multiple pipeline runs to share the same state, ensuring consistency across deployments.

It is configured in the main.tf file with the following backend block under the terraform section:

backend "http" {
  skip_cert_verification = true
}

For more details on how this is set up, refer to the GitLab Docs.

Step 3: Make a change

The best way to see the CI/CD pipeline in action is to make a configuration change. You'll add the global configuration (from Task 03 - Global Configuration and Task 06 - Variables). This includes the login banner and hostnames. To edit the configuration files, you'll use GitLab's built-in Web IDE - an editor similar to VS Code that runs directly in your browser.

Open the web IDE

1. From the project page, click the Edit dropdown button (with a pencil icon)
2. Select Web IDE

The Web IDE opens with a familiar VS Code-like interface:

Lab configuration files

Take a look at the data/ folder in the file explorer (left panel). This folder contains the same configuration files used in Tasks 2-6. However, some file extensions have been changed from .yaml to .yaml_ (with an underscore at the end). This was done intentionally to ignore these files for now.

For this task, you'll rename one file (the global config from Tasks 03 and 06) to enable it, and let the pipeline do the rest.

Add global configuration

1. In the file explorer (left panel), navigate to the data folder
2. Find the file global.nac.yaml_ (note the underscore at the end)
3. Right-click on the file and select Rename
4. Rename the file from global.nac.yaml_ to global.nac.yaml (remove the underscore)
5. Click on the file to open it and inspect the banner content:

---
iosxe:
  global:
    configuration:
      banner:
        login: |
          #########################################
          #                                       #
          #   Welcome to the IOS XE as Code Lab!  #
          #           GitLab - CI/CD              #
          #                                       #
          #########################################
          Device: ${HOSTNAME}
      system:
        hostname: ${HOSTNAME}

Optionally, you can also change the banner text to something new, if you'd like.

Step 4: Commit change to trigger pipeline

1. Click on Source Control icon in the left sidebar
2. You'll see your modified file listed
3. Enter a commit message:

   Add global config for banner and hostname
   

4. Click Commit and push to 'main'
5. If prompted with “You're committing your changes to the default branch. Do you want to continue?”. Select Continue.

Step 5: Monitor pipeline execution

To view the pipeline progress, navigate to Build → Pipelines in the left sidebar, then click on the top pipeline showing running status.

You'll see each stage progressing:

1. validate - green checkmark when YAML validation passes. Usually <10s.
2. plan - generates the Terraform plan against the live devices. ~30-60s.
3. deploy - applies the configuration to the four CML devices over NETCONF. ~60-90s.
4. notify - sends success or failure notifications (not used in this lab). <5s.

End-to-end a healthy pipeline run completes in about 2-3 minutes. If the deploy stage sits on "running" for more than 4-5 minutes, one of the CML devices is probably unreachable - click into the job to see the NETCONF error. (The troubleshooting section below covers the most common causes.)

Click on any stage to view its detailed logs.

Step 6: Verify pipeline success

When all stages complete successfully, the pipeline shows a green passed status.

Verify the deploy job actually changed the devices

A green pipeline only tells you the stages finished without error - it doesn't by itself prove the devices changed. A no-op deploy (running on a state that already matches intent) also shows green. To confirm Terraform actually pushed something, click into the deploy job and scroll to the end of the log. You're looking for a line like:

Apply complete! Resources: 12 added, 0 changed, 0 destroyed.

• Resources > 0 in added or changed - the devices were modified.
• All zeros - the pipeline ran against a state that already matched; nothing was pushed. That's fine, but if you expected a change, verify your commit made it into main and re-trigger the pipeline.

This log-based check is more reliable than looking at device output because it comes straight from the Terraform engine's own accounting.

Spot-check a device (optional but satisfying)

1. Open Solar-PuTTY from your desktop
2. Connect to one of the devices (e.g., core switch)
3. Check the banner and hostname - The banner will now include GitLab - CI/CD

Validation test (optional)

Additionally, you can test the validation stage by introducing an error in the configuration, just like in Task 10 - Schema Validation.

If the validation fails, the pipeline will stop, and you'll see a red failed status.

Troubleshooting common pipeline failures

If your pipeline shows a red failed status, click into the failing job to see the logs. Here are the failure modes you're most likely to hit during the lab:

terraform force-unlock <lock-id>

TF_LOG=DEBUG
TF_LOG_PATH=terraform-debug.log

What you've accomplished

• ✅ Accessed GitLab and navigated to the NaC-IOSXE project
• ✅ Understood the CI/CD pipeline configuration
• ✅ Triggered a pipeline by committing a change
• ✅ Monitored pipeline execution through all stages

What's next

Tasks 14 and 15 are optional - Task 14 extends the pipeline with integration and idempotency tests; Task 15 introduces merge-request workflows with protected branches. If you're at the end of your time box, skip straight to the Conclusion.

← Previous: Task 12 - Cleanup · Next: Task 14 - Extend CI/CD pipeline