Core Resources

ClusterConfig

Cluster configuration, or simply ClusterConfig, acts the sole source of truth for all global configurations and settings of the Cluster. You can read more about managing ClusterConfig here.

Service

Each protected resource is represented in the Cluster by a Service. A Service is implemented by an identity-aware proxy (IaP) called Vigil abstracting all dynamic network-layer details of the protected resource behind it and is capable of providing access control and visibility the application-layer for various protocols including HTTP, SSH, PostgreSQL, MySQL, among others. A protected resource can be running in any private network (e.g. on prem, private cloud, your own laptop behind a NAT, etc...). A protected resource can also be a protected public resource such as SaaS APIs, databases and SSH servers. You can read in detail about Service management here.

User

An Octelium User denotes to the entity that interacts with the Octelium Cluster and access its Services. A User can be HUMAN (used by humans) or WORKLOAD (used by non-human entities such as containers, servers, programmable environments, etc...). In order for Users to be able to interact with an Octelium Cluster, they must first obtain a valid Session.

During the installation of the Octelium Cluster, Octelium automatically creates a User called root with full permissions to control the Cluster. The User root or other Users created later having Administrator permissions can create more Users. A User may belong to one or more Octelium Groups.

A User can be managed both interactively using the octeliumctl create user and declaratively (which is the recommended way) using octeliumctl apply. Here is an example of a User resource. You can know more about the User resource from the API reference here.

1
kind: User
2
metadata:
3
  name: user-1
4
spec:
5
  type: HUMAN
6
  email: [email protected]

Group

A User may belong to one or more Groups. A Group is simply a way to collect Users in order to enforce rules and policies to a whole set of Users instead of applying them to each one (read more about access control here).

A Group can be managed both interactively using the octeliumctl create group and declaratively (which is the recommended way) using octeliumctl apply. Here is an example of a Group resource. You can know more about the Group from the API reference here.

1
kind: Group
2
metadata:
3
  name: group-1
4
spec: {}

Session

A User can interact with the Octelium Cluster and access its Services only through a valid Session that is automatically created upon a successfull authentication. Once the Session expires it gets automatically deleted by the Cluster. A Session can also be deleted manually either by the authenticated User using the octelium logout/ octeliumctl logout commands or by the Cluster administrators using the octeliumctl delete session command.

Namespace

An Octelium Namespace provides a mechanism for isolating groups of Services within the Cluster according to the needs of the Cluster administrators. A Service belongs to one Namespace and thus the name of the Service must be unique among all Services within a Namespace. There are no practical limits as to how many Namespaces that can be created. By default, the Cluster creates a default Namespace with the name default upon the Cluster's installation, when you do not explicitly set a Service to a user-defined Namespace, the Service automatically belongs to the default Namespace.

A Namespace can be managed both interactively using the octeliumctl create namespace and declaratively (which is the recommended way) using octeliumctl apply. Here is an example of a Namespace resource. You can know more about the Namespace resource from the API reference here.

1
kind: Namespace
2
metadata:
3
  name: ns1
4
spec: {}

Secret

A Secret is very similar to Kubernetes secrets. A Secret is a type dedicated for storing sensitive data such as API tokens and passwords where they can be used and referenced by other Cluster resources by the Secret's name in order to not store sensitive data along with other Cluster configurations which can stored in git repositories for example. You can read in detail about Secret management here. Secrets are used by various other Cluster resources such as Services for example to provide secret-less access(read more here).

Device

A Device is a representation by the Cluster of a User's machine. A Device can be optionally registered/enrolled by a logged-in User via the command octelium auth device register or simply octelium auth dev register (read more here). However, it's up to access control to allow or deny a User based on their Device information. You can read more about Device management here.

Credential

A Credential is simply a credential issued by the Cluster to a certain User in the form of a JWT-like token in order to be used later for authentication. A Credential can have one of the 3 types: authentication tokens, OAuth2 client credentials and access tokens. You can read in detail about Credential management here.

Gateway

Each Kubernetes node that is part of the data plane of the Cluster acts as a Gateway and a host for the Services running on that Kubernetes data plane node. A Gateway primarily maintains the WireGuard/QUIC tunnel interfaces via a component called the Gateway Agent.

IdentityProvider

An IdentityProvider represents an identity provider (IdP) that is used by the Cluster to authenticate and re-authenticate the Users in order for them to obtain and keep a valid Session to be able to interact with the Cluster and access its Services. An IdentityProvider has one of the following types: github, oidc, saml, and oidcIdentityToken. Read more about managing IdentityProviders here.

Region

A single Octelium Cluster is designed to run on top of a single Kubernetes cluster or be distributed over multiple Kubernetes clusters. Each Kubernetes cluster acts as a single Region of the Cluster. The initial Kubernetes cluster represents the default Region upon which Services are deployed by default. You, however, can explicitly specify which Region a Service should be deployed on for better latency or other reasons (read more here).