Ingress

The ingress resource creates network traffic routing between local machine and cluster services. It enables exposing Kubernetes/Nomad cluster services to users or exposing local services to clusters for testing and development.

Use Cases

As a lab author, you can use ingress resources to provide access to cluster services:

• Web Application Access: Expose web applications running in Kubernetes/Nomad clusters for users to interact with
• Dashboard Exposure: Provide access to monitoring dashboards (e.g. Grafana, Prometheus UI) or admin interfaces
• API Testing: Expose REST APIs or microservices for users to test and explore
• Database Interfaces: Give access to database admin tools or query interfaces running in clusters
• Development Workflows: Enable local-to-cluster connectivity for development and debugging scenarios
• Service Discovery Labs: Demonstrate how external traffic reaches cluster services through ingress controllers

Ingress resources bridge the gap between isolated cluster environments and participant access, enabling realistic scenarios without complex networking setup.

HCL Syntax

Basic Syntax

resource "ingress" "name" {
  port = 8080

  target {
    resource = resource.kubernetes_cluster.k8s
    port     = 80

    config = {
      service   = "my-service"
      namespace = "default"
    }
  }
}

Full Syntax

resource "ingress" "name" {
  port          = 8080
  expose_local  = false

  target {
    resource  = resource.kubernetes_cluster.k8s
    port      = 80
    named_port = "http"

    config = {
      service   = "kubernetes-dashboard"
      namespace = "kubernetes-dashboard"
    }
  }
}

Fields

Field	Required	Type	Description
port	✓	number	Local port to expose the service on
target	✓	block	Target configuration for traffic routing
expose_local		bool	Direction: false = cluster→local, true = local→cluster. Defaults to false.

Target Configuration

ingress → target

Defines the traffic routing target and configuration.

Field	Required	Type	Description
resource	✓	reference to kubernetes_cluster or nomad_cluster	Reference to target cluster resource
port		number	Target port number
named_port		string	Named port (alternative to port number)
config	✓	map(string)	Target-specific configuration

Kubernetes Config Options

ingress → target → config

For Kubernetes cluster targets, the config map supports:

Config Key	Required	Description
service	✓	Kubernetes service name
namespace	✓	Kubernetes namespace

Nomad Config Options

ingress → target → config

For Nomad cluster targets, the config map supports:

Config Key	Required	Description
job	✓	Nomad job name
group	✓	Nomad task group name
task	✓	Nomad task name

Computed Attributes

These attributes are available after ingress creation:

Field	Type	Description
ingress_id	string	Internal ingress service ID
local_address	string	Full local URI for accessing the service
remote_address	string	Full remote URI for the service

Validation Rules

• Reserved ports: Cannot use ports 60000 or 60001 (reserved for internal use)
• Reserved names: Cannot use “connector” as resource name
• Target reference: Must reference valid cluster resources
• Config requirements: Kubernetes targets require service and namespace

Traffic Direction

Cluster to Local (Default)

expose_local = false - Expose cluster services to users:

resource "ingress" "app_access" {
  port = 8080

  target {
    resource = resource.kubernetes_cluster.k8s
    port     = 80

    config = {
      service   = "my-web-app"
      namespace = "default"
    }
  }
}

Local to Cluster

expose_local = true - Expose local services to cluster:

resource "ingress" "local_api" {
  port         = 3000
  expose_local = true

  target {
    resource = resource.kubernetes_cluster.k8s

    config = {
      service   = "local-dev-api"
      namespace = "default"
    }
  }
}

Examples

Expose Kubernetes Dashboard

resource "ingress" "k8s_dashboard" {
  port = 8080

  target {
    resource = resource.kubernetes_cluster.training
    port     = 443

    config = {
      service   = "kubernetes-dashboard"
      namespace = "kubernetes-dashboard"
    }
  }
}

Expose Web Application

resource "ingress" "webapp" {
  port = 8080

  target {
    resource = resource.kubernetes_cluster.cluster
    port     = 80

    config = {
      service   = "nginx-service"
      namespace = "web"
    }
  }
}

Expose Database Admin Interface

resource "ingress" "pgadmin" {
  port = 5050

  target {
    resource = resource.kubernetes_cluster.database
    port     = 80

    config = {
      service   = "pgadmin"
      namespace = "database"
    }
  }
}

Expose API with Named Port

resource "ingress" "api_server" {
  port = 8000

  target {
    resource   = resource.kubernetes_cluster.api
    named_port = "api"

    config = {
      service   = "api-service"
      namespace = "api"
    }
  }
}

Multiple Service Exposure

resource "ingress" "frontend" {
  port = 3000

  target {
    resource = resource.kubernetes_cluster.app
    port     = 80

    config = {
      service   = "frontend-service"
      namespace = "web"
    }
  }
}

resource "ingress" "backend" {
  port = 3001

  target {
    resource = resource.kubernetes_cluster.app
    port     = 8080

    config = {
      service   = "backend-service"
      namespace = "api"
    }
  }
}

resource "ingress" "database" {
  port = 5432

  target {
    resource = resource.kubernetes_cluster.app
    port     = 5432

    config = {
      service   = "postgres"
      namespace = "database"
    }
  }
}

Usage in Service Resources

Ingress resources are commonly referenced by service resources:

resource "service" "webapp" {
  target = resource.ingress.webapp
}

resource "layout" "app_layout" {
  column {
    instructions {}
  }

  column {
    tab "app" {
      target = resource.service.webapp
      title  = "Web Application"
      active = true
    }
  }
}

Best Practices

1. Port Organization: Use consistent port ranges for different service types
2. Service Discovery: Use meaningful service names that match Kubernetes deployments
3. Namespace Management: Organize services by namespace for clarity
4. Security: Be cautious when exposing database or admin interfaces
5. Documentation: Clearly document exposed services and their purposes
6. Testing: Verify ingress connectivity before lab deployment

Common Issues

Service Not Found

## Verify service exists in cluster
kubectl get svc -n namespace-name

# Check ingress configuration
resource "ingress" "app" {
  target {
    config = {
      service   = "correct-service-name"  # Must match kubectl output
      namespace = "correct-namespace"     # Must match kubectl output
    }
  }
}

Port Conflicts

# Ensure unique local ports
resource "ingress" "app1" { port = 8080 }
resource "ingress" "app2" { port = 8081 }  # Different port

Connection Issues

# Check cluster connectivity
kubectl port-forward svc/service-name port:port -n namespace

# Verify ingress target matches
resource "ingress" "app" {
  port = 8080  # This is the local port users access

  target {
    port = 80  # This must match the service port in Kubernetes
  }
}