Services

A Service in Riptides represents a network endpoint that workloads connect to. Services define the destinations in your infrastructure: both internal services secured by Riptides and external APIs that workloads need to reach.

What Services Represent

Services are the “other side” of a workload connection. When you define connection policies on a WorkloadIdentity (egress rules), you reference services to specify which destinations a workload is allowed to reach. Services decouple connection policy from network addresses: you define intent (this workload connects to the payment API) rather than infrastructure details (this workload connects to 10.0.3.42:443).

Internal vs External Services

Internal Services

Internal services represent endpoints within your infrastructure that are also managed by Riptides. Connections between workloads and internal services can be secured with mutual TLS, with both sides presenting SPIFFE identities. Access control policies can restrict connections based on the SPIFFE IDs of the connecting workload.

An internal service might represent a database, a message broker, or another microservice running in the same or a different cluster.

External Services

External services represent endpoints outside your infrastructure or outside Riptides management. These include cloud provider APIs (such as AWS S3 or GCP Cloud Storage), third-party SaaS APIs, or legacy systems that do not participate in the SPIFFE trust domain.

For external services, Riptides can inject credentials into outbound connections, apply TLS policies, and enforce which workloads are allowed to connect.

Service Definition

A Service resource specifies the endpoint address, port, protocol, and metadata used for policy matching:

apiVersion: core.riptides.io/v1alpha1
kind: Service
metadata:
  name: payment-api
  namespace: riptides-system
spec:
  addresses:
    - address: payment-api.internal.example.com
      port: 443
  labels:
    team: payments
    tier: backend

Addresses

The addresses field specifies how the service is reached. Each entry is an object with:

• address: A DNS hostname (api.example.com), IP address (10.0.3.42), FQDN, or wildcard FQDN (*.example.com).
• port: The port number the service listens on.
• aliases: Alternative hostnames that should be treated as the same service.

A service can have multiple address entries, for example when it is reachable on different ports or through different DNS names.

Wildcard Addresses

A wildcard address like *.s3.amazonaws.com isn’t a single resolvable hostname, so the kernel can’t enforce access to it just by DNS lookup. For a wildcard address to be enforceable, the Service must also specify the actual network range it covers, using one of:

• networkPrefixes: Explicit CIDR ranges (e.g. 10.0.0.0/16) that the wildcard resolves to.
• networkNames: Symbolic, provider-backed names (aws, azure, google, google-cloud, github, optionally narrowed to a specific service like aws:s3) that the daemon resolves to that provider’s published IP ranges at runtime, so the enforced range stays current as the provider adds or retires addresses. See the Service reference for the full list.

A small set of well-known provider wildcards, such as *.amazonaws.com and *.googleapis.com, are recognized automatically and don’t require networkPrefixes or networkNames to be set. Any other wildcard address without one of these fields is rejected at admission time, since Riptides would otherwise have no way to know which network range the wildcard is meant to cover.

Labels and Policy Matching

Services use labels for categorization and policy matching. WorkloadIdentity egress rules reference services by label selectors rather than by name, enabling flexible grouping.

For example, a WorkloadIdentity might allow egress to all services labeled tier: backend:

apiVersion: core.riptides.io/v1alpha1
kind: WorkloadIdentity
metadata:
  name: frontend
  namespace: riptides-system
spec:
  workloadID: myapp/frontend
  selectors:
    - k8s:label:app: frontend
  egress:
    - selectors:
        - tier: backend
      connection:
        tls:
          mode: MUTUAL

This approach means you can add new backend services without updating every workload policy that needs access to them. Apply the tier: backend label to the new service, and existing policies automatically include it.

Examples

External Cloud API

apiVersion: core.riptides.io/v1alpha1
kind: Service
metadata:
  name: aws-s3
  namespace: riptides-system
spec:
  addresses:
    - address: s3.us-east-1.amazonaws.com
      port: 443
  external: true
  labels:
    provider: aws
    type: storage

Internal Database

apiVersion: core.riptides.io/v1alpha1
kind: Service
metadata:
  name: orders-db
  namespace: riptides-system
spec:
  addresses:
    - address: orders-db.internal.example.com
      port: 5432
  labels:
    tier: backend
    type: database

Wildcard Address

*.s3.amazonaws.com is not one of the automatically recognized provider wildcards, so this Service must supply the network range it covers explicitly:

apiVersion: core.riptides.io/v1alpha1
kind: Service
metadata:
  name: aws-s3-buckets
  namespace: riptides-system
spec:
  addresses:
    - address: "*.s3.amazonaws.com"
      port: 443
      networkNames:
        - aws:s3
  external: true
  labels:
    provider: aws
    type: storage