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. Every TwingateResourceAccess referencing it is reconciled as soon as the new ID is recorded, which takes the grant away from the old resource ID and applies it to the new one.

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.