Ingress

Defined insandbox.hcl

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:

• Cluster Service Access: Expose web applications running in Kubernetes/Nomad clusters for users to interact with
• 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 user 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	Type	Required	Description
port	number	✓	Local port to expose the service on Constraintsport %v is reserved for internal use
expose_local	bool	—	Expose a local service to the target
target	block	✓	Target traffic destination
open_in_browser	string	—	Path to open in the browser

Target

ingress→Target

Target traffic destination

Field	Type	Required	Description
resource	referencecontainer, vm, k8s_cluster, nomad_cluster	✓	Target resource to route traffic to
port	number	—	Target port
named_port	string	—	Named port on the target
config	map(string)	✓	Driver-specific configuration

Computed Attributes

These attributes are set by the system and are read-only.

Attribute	Type	Description
ingress_id	string	ID of the created connector service
local_address	string	Fully qualified URI for accessing from the local machine
remote_address	string	Fully qualified URI for accessing in the remote machine

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
  }
}