IPPolicy

IPPolicy custom resource

apiVersion: `ingress.k8s.ngrok.com/v1alpha1`

kind: `IPPolicy`

IP Policies define rules that allow or deny traffic based on the source IP of connections to your ngrok endpoints. These policies can be attached to endpoints via Traffic Policy configurations to control access based on IP addresses and CIDR ranges. IP Policies consist of one or more rules, where each rule specifies:

An action (allow or deny)
A CIDR range to match against
An optional description

IPPolicy structure and types

The following outlines the high level structure and typings of an IPPolicy

apiVersion: ingress.k8s.ngrok.com/v1alpha1
kind: IPPolicy
metadata:
  name: <string>
  namespace: <string>
spec:
  description: <string>       # optional, default: ""
  metadata: <string>          # optional, default: "{"owned-by":"kubernetes-ingress-controller"}"
  rules: <[]Object>           # required
  - action: <string>          # required, enum: "allow" | "deny"
    cidr: <string>            # required
    description: <string>     # optional
    metadata: <string>        # optional

IPPolicy fields

The following sections outline each field of the IPPolicy custom resource, whether they are required, what their default values are (if applicable), and a description of their purpose/constraints.

`spec`

spec defines the desired state of the IPPolicy Type: Object Required: yes Default: none Fields:

Field Name	Type	Required	Default	Description
`spec.description`	`string`	no	`""`	Human-readable description for this `IPPolicy` to help identify/describe it
`spec.metadata`	`string`	no	`"{"owned-by":"kubernetes-ingress-controller"}"`	String of arbitrary data associated with the object in the ngrok API/Dashboard
`spec.rules`	`[]Object`	yes	none	List of rules that define which IPs/CIDR ranges to allow or deny

`spec.description`

Human-readable description of this IP Policy that can be used to help identify/describe it. Type: string Required: no Default: ""

`spec.metadata`

String of arbitrary data associated with the object in the ngrok API/Dashboard. Type: string Required: no Default: "{"owned-by":"kubernetes-ingress-controller"}"

`spec.rules`

List of rules that define which IP addresses or CIDR ranges should be allowed or denied access. Each rule is evaluated independently, and the most specific matching rule applies. Type: []Object Required: yes Default: none Fields:

Field Name	Type	Required	Default	Description
`spec.rules[].action`	`string` (enum)	yes	none	Whether to allow or deny traffic from the specified CIDR range
`spec.rules[].cidr`	`string`	yes	none	IP address or CIDR range to match against
`spec.rules[].description`	`string`	no	`""`	Human-readable description for this rule
`spec.rules[].metadata`	`string`	no	none	String of arbitrary data associated with the rule in the ngrok API/Dashboard

`spec.rules[].action`

Specifies whether to allow or deny traffic from the IP addresses matching this rule’s CIDR range. Type: string (enum) Required: yes Default: none Allowed Values: "allow", "deny"

`spec.rules[].cidr`

IP address or CIDR range to match against the source IP of incoming connections. This must be a valid IPv4 or IPv6 CIDR notation. Type: string Required: yes Default: none Examples:

Single IP: 192.168.1.1/32
Subnet: 10.0.0.0/24
IPv6: 2001:db8::/32

`spec.rules[].description`

Human-readable description of this rule that can be used to help identify/describe it. Type: string Required: no Default: ""

`spec.rules[].metadata`

String of arbitrary data associated with this rule in the ngrok API/Dashboard. Type: string Required: no Default: none

Status fields

The IPPolicy resource includes status information that reflects the current state of the policy in the ngrok system.

`status.id`

The ngrok API ID for this IP Policy resource. Type: string Example: ipp_34iZT0muBP3kpcAXxGjM4uFlgDK

`status.rules`

Array of rules with their ngrok API IDs. Each rule status includes the rule ID, CIDR, and action that was configured. Type: []Object Example:

rules:
- id: ipr_34iZT1AbCdEfGhIjKlMnOpQrStU
  cidr: 162.236.158.182/32
  action: allow

`status.conditions`

Standard Kubernetes conditions that indicate the state of the IP Policy. Type: []Condition Each condition includes:

type - The condition type
status - True, False, or Unknown
reason - A programmatic identifier for the condition state
message - A human-readable description
lastTransitionTime - When the condition last changed
observedGeneration - The resource generation this condition applies to

Condition types

`Ready`

Indicates whether the IP Policy is fully operational and ready to use. Status Values:

True - IP Policy is active and ready
False - IP Policy is not ready (see reason for details)

Reasons:

Reason	Status	Meaning
`IPPolicyActive`	`True`	IP Policy is successfully created and active
`IPPolicyRulesConfigurationError`	`False`	One or more rules failed to configure
`IPPolicyCreationFailed`	`False`	Failed to create the IP Policy in ngrok
`IPPolicyInvalidCIDR`	`False`	One or more rules have invalid CIDR notation

Example:

conditions:
- type: Ready
  status: "True"
  reason: IPPolicyActive
  message: "IP Policy is active"
  lastTransitionTime: "2025-10-29T00:39:16Z"
  observedGeneration: 1

`IPPolicyCreated`

Indicates whether the IP Policy was successfully created in the ngrok API. Status Values:

True - IP Policy was successfully created
False - Failed to create IP Policy

Reasons:

Reason	Status	Meaning
`IPPolicyCreated`	`True`	IP Policy successfully created
`IPPolicyCreationFailed`	`False`	API call to create IP Policy failed

Example:

conditions:
- type: IPPolicyCreated
  status: "True"
  reason: IPPolicyCreated
  message: "IP Policy successfully created"
  lastTransitionTime: "2025-10-29T00:39:16Z"
  observedGeneration: 1

`RulesConfigured`

Indicates whether all rules have been successfully configured for the IP Policy. Status Values:

True - All rules are configured
False - One or more rules failed to configure

Reasons:

Reason	Status	Meaning
`IPPolicyRulesConfigured`	`True`	All rules successfully configured
`IPPolicyRulesConfigurationError`	`False`	One or more rules failed validation or creation
`IPPolicyInvalidCIDR`	`False`	One or more rules have invalid CIDR notation

Example:

conditions:
- type: RulesConfigured
  status: "True"
  reason: IPPolicyRulesConfigured
  message: "All rules configured for IP Policy"
  lastTransitionTime: "2025-10-29T00:39:16Z"
  observedGeneration: 1

Status examples

Successfully created IP Policy

status:
  id: ipp_34iZT0muBP3kpcAXxGjM4uFlgDK
  rules:
  - id: ipr_34iZT1AbCdEfGhIjKlMnOpQrStU
    cidr: 162.236.158.182/32
    action: allow
  conditions:
  - type: IPPolicyCreated
    status: "True"
    reason: IPPolicyCreated
    message: "IP Policy successfully created"
    lastTransitionTime: "2025-10-29T00:39:16Z"
    observedGeneration: 1
  - type: RulesConfigured
    status: "True"
    reason: IPPolicyRulesConfigured
    message: "All rules configured for IP Policy"
    lastTransitionTime: "2025-10-29T00:39:16Z"
    observedGeneration: 1
  - type: Ready
    status: "True"
    reason: IPPolicyActive
    message: "IP Policy is active"
    lastTransitionTime: "2025-10-29T00:39:16Z"
    observedGeneration: 1

IP Policy with Invalid CIDR

status:
  conditions:
  - type: IPPolicyCreated
    status: "False"
    reason: IPPolicyCreationFailed
    message: "Failed to create IP Policy: invalid CIDR notation in rule"
    lastTransitionTime: "2025-10-29T00:39:15Z"
    observedGeneration: 1
  - type: RulesConfigured
    status: "False"
    reason: IPPolicyInvalidCIDR
    message: "Invalid CIDR range: 192.168.1.0/42 (prefix length must be between 0 and 32 for IPv4)"
    lastTransitionTime: "2025-10-29T00:39:15Z"
    observedGeneration: 1
  - type: Ready
    status: "False"
    reason: IPPolicyInvalidCIDR
    message: "IP Policy cannot be activated due to invalid CIDR in rules"
    lastTransitionTime: "2025-10-29T00:39:15Z"
    observedGeneration: 1

Checking IP Policy status

You can check the status of an IP Policy using kubectl:

# Check if IP Policy is ready
kubectl get ippolicy whitelist-specific-ip -o jsonpath='{.status.conditions[?(@.type=="Ready")]}'

# Watch for IP Policy to become ready
kubectl wait --for=condition=Ready ippolicy/whitelist-specific-ip --timeout=60s

# Get all IP Policies with their ready status
kubectl get ippolicies -A -o custom-columns=\
NAME:.metadata.name,\
NAMESPACE:.metadata.namespace,\
READY:.status.conditions[?(@.type==\'Ready\')].status,\
REASON:.status.conditions[?(@.type==\'Ready\')].reason

# View all rules and their IDs
kubectl get ippolicy whitelist-specific-ip -o jsonpath='{.status.rules[*]}'

Example IPPolicies

Allow specific IP address

The following IPPolicy allows traffic only from a specific IP address:

apiVersion: ingress.k8s.ngrok.com/v1alpha1
kind: IPPolicy
metadata:
  name: whitelist-specific-ip
  namespace: default
spec:
  description: IP Policy to whitelist specific IP address
  rules:
  - action: allow
    cidr: 162.236.158.182/32
    description: Allow access from specific IP address

Allow subnet with multiple rules

The following IPPolicy allows traffic from a corporate network subnet:

apiVersion: ingress.k8s.ngrok.com/v1alpha1
kind: IPPolicy
metadata:
  name: corporate-network-access
  namespace: production
spec:
  description: Allow access from corporate network
  rules:
  - action: allow
    cidr: 10.0.0.0/16
    description: Allow access from main corporate subnet
  - action: allow
    cidr: 172.16.0.0/12
    description: Allow access from corporate VPN range

Deny specific IP addresses

The following IPPolicy denies traffic from specific IP addresses:

apiVersion: ingress.k8s.ngrok.com/v1alpha1
kind: IPPolicy
metadata:
  name: blocklist
  namespace: default
spec:
  description: Block traffic from malicious IPs
  rules:
  - action: deny
    cidr: 192.0.2.1/32
    description: Blocked IP from abuse reports
  - action: deny
    cidr: 198.51.100.0/24
    description: Blocked subnet from attack attempts

Quickstarts

Manage

Load Balancing

Usage Guides

Custom Resources

Integrations & Platforms

IPPolicy custom resource

apiVersion: `ingress.k8s.ngrok.com/v1alpha1`

kind: `IPPolicy`

IPPolicy structure and types

IPPolicy fields

`spec`

`spec.description`

`spec.metadata`

`spec.rules`

`spec.rules[].action`

`spec.rules[].cidr`

`spec.rules[].description`

`spec.rules[].metadata`

Status fields

`status.id`

`status.rules`

`status.conditions`

Condition types

`Ready`

`IPPolicyCreated`

`RulesConfigured`

Status examples

Successfully created IP Policy

IP Policy with Invalid CIDR

Checking IP Policy status

Example IPPolicies

Allow specific IP address

Allow subnet with multiple rules

Deny specific IP addresses

​IPPolicy custom resource

​apiVersion: ingress.k8s.ngrok.com/v1alpha1

​kind: IPPolicy

​IPPolicy structure and types

​IPPolicy fields

​spec

​spec.description

​spec.metadata

​spec.rules

​spec.rules[].action

​spec.rules[].cidr

​spec.rules[].description

​spec.rules[].metadata

​Status fields

​status.id

​status.rules

​status.conditions

​Condition types

Ready

IPPolicyCreated

RulesConfigured

​Status examples

​Successfully created IP Policy

​IP Policy with Invalid CIDR

​Checking IP Policy status

​Example IPPolicies

​Allow specific IP address

​Allow subnet with multiple rules

​Deny specific IP addresses

IPPolicy custom resource

apiVersion: `ingress.k8s.ngrok.com/v1alpha1`

kind: `IPPolicy`

IPPolicy structure and types

IPPolicy fields

`spec`

`spec.description`

`spec.metadata`

`spec.rules`

`spec.rules[].action`

`spec.rules[].cidr`

`spec.rules[].description`

`spec.rules[].metadata`

Status fields

`status.id`

`status.rules`

`status.conditions`

Condition types

`Ready`

`IPPolicyCreated`

`RulesConfigured`

Status examples

Successfully created IP Policy

IP Policy with Invalid CIDR

Checking IP Policy status

Example IPPolicies

Allow specific IP address

Allow subnet with multiple rules

Deny specific IP addresses