Cluster Configuration

Cluster configuration, or simply ClusterConfig, acts as the sole source of truth for all global configurations and settings of the Cluster. ClusterConfig is created automatically upon the Cluster installation and can be updated declaratively via the command octeliumctl apply (read more here). You can read the entire Cluster configuration in the ClusterConfig JSON Schema.

You can get the ClusterConfig as follows:

octeliumctl get clusterconfig
# OR Simply
octeliumctl get cc
# OR as JSON
octeliumctl get clusterconfig -o json

Session

Users can interact with a Cluster and access its Services as long as their Sessions are valid (read more about Session management here). A Session has a duration after which the Session expires and automatically gets deleted by the Cluster. It's recommended that the Session's duration should be as short as possible without becoming too annoying especially for HUMAN Users. The current fallback value for access token duration is 4 hours but it might change in the future.

You can set your own Session duration configuration as follows:

kind: ClusterConfig
metadata:
  name: cluster-config
spec:
  session:
    human:
      clientDuration:
        days: 1
      clientlessDuration:
        hours: 10
      maxPerUser: 32
      accessTokenDuration:
        hours: 4
      refreshTokenDuration:
        hours: 18
      defaultState: PENDING
    workload:
      clientDuration:
        months: 6
      clientlessDuration:
        weeks: 1
      maxPerUser: 100
      accessTokenDuration:
        hours: 4
      refreshTokenDuration:
        weeks: 2
      defaultState: ACTIVE

These Cluster-wide Session duration values can be overridden per User basis. You can read more here.

Device

Octelium enables you to control Device related configurations (read more about Devices here). For example, you can explicitly define the default state of a new registered Device. By default, a Device's default state is set to ACTIVE, however, you can override that choice to PENDING or REJECTED. You can also set a per-User limit as follows:

kind: ClusterConfig
metadata:
  name: cluster-config
spec:
  device:
    human:
      maxPerUser: 32
      defaultState: PENDING
    workload:
      maxPerUser: 100
      defaultState: ACTIVE

Gateway

Octelium enables you to control the rotation duration of the Gateways WireGuard keys as follows:

kind: ClusterConfig
metadata:
  name: cluster-config
spec:
  gateway:
    wireguardKeyRotationDuration:
      hours: 6

Ingress

You can choose to use the useForwardedForHeader field to enable the usage of the X-Forwarded-For header by the Cluster to obtain the downstream's public IP address. The downstream's IP address is mainly stored in the Session and can be used via your Policies to control access to Services. This is also useful for geolocation-based access control (read more here). Here is an example:

kind: ClusterConfig
metadata:
  name: cluster-config
spec:
  ingress:
    useForwardedForHeader: true

You can explicitly set the number of trusted hops in the returned value of the X-Forwarded-For header (read more here) via the xffNumTrustedHops field. Here is an example:

kind: ClusterConfig
metadata:
  name: cluster-config
spec:
  ingress:
    useForwardedForHeader: true
    xffNumTrustedHops: 1

DNS

The Cluster automatically serves private DNS, deployed as a typical Service that can be accessed by all, to resolve the domain names of the Cluster's Services to their IP addresses. Moreover, that private DNS Service can also resolve domain names outside the Cluster domain by proxying the requests to a server that is chosen randomly from a list of fallback DNS servers. Both UDP as well as DNS-over-TLS servers are supported. Here is an example:

kind: ClusterConfig
metadata:
  name: cluster-config
spec:
  dns:
    fallbackZone:
      servers:
        - dns://8.8.8.8
        - udp://1.1.1.1
        - tls://8.8.8.8
        - tls://1.1.1.1
        - dns://custom-dns-server:8053

The private DNS Service can also cache the results of the fallback servers. Here is an example:

kind: ClusterConfig
metadata:
  name: cluster-config
spec:
  dns:
    fallbackZone:
      servers:
        - tls://8.8.8.8
        - tls://1.1.1.1
      cacheDuration:
        seconds: 30
    

You can also route the DNS queries of specific domains, and all of their subdomains, to their own DNS servers via the zones list. This can be useful, for example, to resolve your internal corporate domains via your internal DNS servers while all other queries keep going to the fallback servers. Here is an example:

kind: ClusterConfig
metadata:
  name: cluster-config
spec:
  dns:
    fallbackZone:
      servers:
        - tls://8.8.8.8
        - tls://1.1.1.1
    zones:
      - domains:
          - corp.example.com
          - internal.example.com
        servers:
          - 10.0.0.53
          - tls://dns.corp.example.com
        cacheDuration:
          minutes: 1

Each zone must have at least one domain and at least one server, and a domain cannot be used in more than one zone. A query matches a zone if its name is either one of the zone's domains or a subdomain of it. When a query matches multiple zones, the zone with the longest matching domain takes precedence. Queries that do not match any zone are resolved by the fallbackZone. Each zone can also cache its own results via its cacheDuration field. Note that the domain names of the Cluster's Services are always resolved by the Cluster itself.

Authorization

You can define global Policies (read more here) that are always triggered across all the Cluster's requests as follows:

kind: ClusterConfig
metadata:
  name: cluster-config
spec:
  authorization:
    policies: ["pol-1", "pol-2"]
    inlinePolicies:
      - spec:
          rules:
            - effect: DENY
              condition:
                match: '"junior" in ctx.user.spec.groups && ctx.namespace.metadata.name == "production"'

Authentication

Geolocation

Since version v0.23.0, Octelium Clusters support geolocation via MaxMind MMDB databases (enterprise, city and country-type databases are supported). This feature sets geolocation info (e.g. country, city, ASN) in the Session on each authentication where you can use such info in your Policies for access control on a per-request basis (read more here). Here is an example using a database that can be fetched from a URL:

kind: ClusterConfig
metadata:
  name: cluster-config
spec:
  ingress:
    useForwardedForHeader: true
    xffNumTrustedHops: 1

  authentication:
    geolocation:
      mmdb:
        upstream:
          url: https://mmdb-provider.example.com/geoip-city-db.mmdb

As shown in the example above, you need to trust X-Forwarded-For via the useForwardedForHeader field. You can also set the number of trusted hops used in the X-Forwarded-For header via the xffNumTrustedHops field.