Resource Management User Guide

Annotating a Service

Expose a cluster workload by annotating its Service: add resource.twingate.com: "true" under metadata.annotations. Note that "true" is quoted because annotation values are strings, and an unquoted true will be incorrectly interpreted as a boolean.

When you do this, the operator will create a TwingateResource object based on your Service properties, deriving its:

• name - <service-name>-resource (override with the resource.twingate.com/name annotation).
• address - the Service's in-cluster DNS name (<service-name>.<namespace>.svc.cluster.local).
• port restrictions - from the ports the Service exposes.

You can further customize the generated TwingateResource object by adding more annotations on the Service, each matches the respective TwingateResource spec property:

• resource.twingate.com/name - the resource's name in the Twingate Admin Console.
• resource.twingate.com/alias - the resource's alias.
• resource.twingate.com/isBrowserShortcutEnabled - wether the “Open in Browser” should show for this resource.
• resource.twingate.com/securityPolicyId - assign a Security Policy to this resource.
• resource.twingate.com/isVisible - is the resource visible in the client dropdown menu.
• resource.twingate.com/syncLabels - allows turning off the default behaviors of syncing labels as tags to Twingate.
• resource.twingate.com/type - Network (default) or WebApp. WebApp creates an Identity Firewall Web App instead; see Identity Firewall.

A resource's type is immutable, so changing resource.twingate.com/type recreates the generated TwingateResource: the Twingate resource is deprovisioned and re-registered with a new ID, and TwingateResourceAccess grants are reapplied on the next reconcile.

Example:

apiVersion: v1
kind: Service
metadata:
  name: my-service-local
  annotations:
    resource.twingate.com: "true"
    resource.twingate.com/alias: "myapp.internal"
spec:
  selector:
    app.kubernetes.io/name: MyApp
  ports:
    - protocol: TCP
      port: 80
      targetPort: 9376
      name: first
    - protocol: UDP
      port: 22
      targetPort: 9376
      name: second

Granting access

Creating a resource does not make it reachable; you must grant a principal (a Group or Service Account) access to it. Create a TwingateResourceAccess referencing the resource:

apiVersion: twingate.com/v1beta
kind: TwingateResourceAccess
metadata:
  name: my-resource-access
spec:
  resourceRef:
    name: my-resource
  principalExternalRef:
    type: group
    name: DevOps Engineers

This applies to every resource type - Network, Kubernetes, and Web App.

Tagging Resources

Labels set on the TwingateResource object will automatically propagate to Twingate as resource tags. You can disable this behavior by setting syncLabels: false property (see API docs) on the resource:

Example:

apiVersion: twingate.com/v1beta
kind: TwingateResource
metadata:
  name: my-twingate-resource
  labels:
    env: dev
spec:
  name: My K8S Resource
  address: my.default.cluster.local
  syncLabels: false # will prevent syncing labels to twingate

Default Tags

Operator also supports applying a certain set of labels system-wide - to all TwingateResource objects managed by the operator. When deploying the operator you can define defaultResourceTags under twingateOperator in your values.yaml:

twingateOperator:
  defaultResourceTags:
    tag1: value_for_tag1
    tag2: value_for_tag2

Identity Firewall resources

Annotating a Service (above) creates a Network resource, reachable through a Connector with no extra infrastructure. Twingate's Identity Firewall adds two richer resource types that run through an in-cluster Gateway:

• Kubernetes - expose the cluster's API server with the user's identity propagated for RBAC and auditing.
• Web App - expose an in-cluster HTTP app with the user's identity injected into requests.

Both require a Twingate Gateway deployed in the cluster.