Skip to main content

Documentation Index

Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
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 NameTypeRequiredDefaultDescription
spec.descriptionstringno""Human-readable description for this IPPolicy to help identify/describe it
spec.metadatastringno"{"owned-by":"kubernetes-ingress-controller"}"String of arbitrary data associated with the object in the ngrok API/Dashboard
spec.rules[]ObjectyesnoneList 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 NameTypeRequiredDefaultDescription
spec.rules[].actionstring (enum)yesnoneWhether to allow or deny traffic from the specified CIDR range
spec.rules[].cidrstringyesnoneIP address or CIDR range to match against
spec.rules[].descriptionstringno""Human-readable description for this rule
spec.rules[].metadatastringnononeString 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:
ReasonStatusMeaning
IPPolicyActiveTrueIP Policy is successfully created and active
IPPolicyRulesConfigurationErrorFalseOne or more rules failed to configure
IPPolicyCreationFailedFalseFailed to create the IP Policy in ngrok
IPPolicyInvalidCIDRFalseOne 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:
ReasonStatusMeaning
IPPolicyCreatedTrueIP Policy successfully created
IPPolicyCreationFailedFalseAPI 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:
ReasonStatusMeaning
IPPolicyRulesConfiguredTrueAll rules successfully configured
IPPolicyRulesConfigurationErrorFalseOne or more rules failed validation or creation
IPPolicyInvalidCIDRFalseOne 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