Configuration Overview

Gravity borrows the concept of resources from Kubernetes for configuration. Gravity uses the gravity resource command to update the Cluster configuration.

The currently supported resources are:

Resource Name Resource Description
github GitHub connector
oidc OIDC connector (Enterprise only)
saml SAML connector (Enterprise only)
role User role (Enterprise only)
user Cluster user
token User tokens such as API keys
logforwarder Forwarding logs to a remote rsyslog server
trusted_cluster Managing access to remote Gravity Hubs (Enterprise Only)
endpoints Gravity Hub endpoints for user and Cluster traffic (Enterprise Only)
cluster_auth_preference Cluster authentication settings such as second-factor
alert Cluster monitoring alert
alerttarget Cluster monitoring alert target
smtp Cluster monitoring SMTP configuration
runtimeenvironment Cluster runtime environment variables
clusterconfiguration General Cluster configuration
authgateway Authentication gateway configuration
operations Cluster operations

General Cluster Configuration

It is possible to customize the Cluster per environment before the installation or update some aspects of the Cluster using the ClusterConfiguration resource:

kind: ClusterConfiguration
version: v1
    # configures the cloud provider
    cloudProvider: gce
    # free-form cloud configuration
    cloudConfig: |
    # represents the IP range from which to assign service Cluster IPs
    serviceCIDR:  ""
    # port range to reserve for services with NodePort visibility
    serviceNodePortRange: "30000-32767"
    # host port range (begin-end, single port or begin+offset, inclusive) that
    # may be consumed in order to proxy service traffic
    proxyPortRange: "0-0"
    # CIDR range for Pods in Cluster
    podCIDR: ""
    # The size of the Pod subnet allocated to each host
    podSubnetSize: "26"
    # A set of key=value pairs that describe feature gates for alpha/experimental features
      AllAlpha: true
      APIResponseCompression: false
      BoundServiceAccountTokenVolume: false
      ExperimentalHostUserNamespaceDefaulting: true
  # kubelet configuration as described here:
  # and here:
      kind: KubeletConfiguration
      nodeLeaseDurationSeconds: 50

In order to apply the configuration immediately after the installation, supply the configuration file to the gravity install command:

root$ ./gravity install --cluster=<cluster-name> ... --config=Cluster-config.yaml


You can combine multiple kubernetes and Gravity-specific resources in the config file prior to running the install command to have the installer automatically create all resources upon installation.


Setting feature gates overrides the value set by the runtime container by default.

In order to update configuration of an active Cluster, use the gravity resource command:

root$ ./gravity resource create Cluster-config.yaml

The operation can be started in manual mode in which case you have the ability to review the operation plan or cancel the operation. To put the operation into manual mode, use the --manual flag:

root$ ./gravity resource create Cluster-config.yaml --manual

The configuration update is implemented as a Cluster operation. Once created, it is managed using the same gravity plan command described in the Managing Operations section.

To view the configuration:

root$ ./gravity resource get config

To remove (reset to defaults) the configuration:

root$ ./gravity resource rm config


Updating the configuration of an active Cluster is disruptive and might necessitate the restart of runtime containers either on master or on all Cluster nodes. Take this into account and plan each update accordingly.

Cluster Operations

Operations performed on a cluster (install, upgrade, node join or removal, etc.) are exposed via an operation resource.

To see a list of cluster operations:

$ sudo gravity resource get operations
ID                                       Description                                   State         Created
--                                       -----------                                   -----         -------
eb0d0a68-f835-471b-9ceb-500460ffcd0b     Remove node node-2 (           Completed     Tue Apr  7 21:56 UTC
7e95deca-3a71-4abe-8616-097bab26c943     Join node node-2 ( as node     Completed     Tue Apr  7 21:50 UTC
b75f28bc-b8e9-403f-9cda-972013a652e8     1-node install                                Completed     Tue Apr  7 21:37 UTC

To view a particular operation details:

$ sudo gravity resource get operation 7e95deca-3a71-4abe-8616-097bab26c943 --format=json

The operation resource is read-only and, as such, not supported by the resource create and delete commands.

Cluster Access

Gravity supports the creation of multiple users. Roles can also be created and assigned to users which can be mapped to Kubernetes role based access control authorization (RBAC API). Gravity can also integrate with third party identity providers through standard protocols like OIDC and SAML.

Enterprise Only Version Warning

The Community version of Gravity only supports local users and integration with Github identity. Gravity Enterprise supports additional identity provider integrations.

Configuring Roles

Below is an example of a resource file with the definition of an admin role. The admin has access to all resources, including roles, other users and authentication settings, and belongs to a privileged Kubernetes group:

kind: role
version: v3
  name: administrator
    - admin
    - root
      '*': '*'
    - resources:
      - '*'
      - '*'
    max_session_ttl: 30h0m0s

Below is an example of a non-admin role spec providing access to a particular Cluster and its applications:

kind: role
version: v3
  name: developer
    - root
      '*': '*'
    - admin
    - resources:
      - role
      - read
    - resources:
      - app
      - list
    - resources:
      - cluster
      - read
      - update
      where: equals(, "")
    max_session_ttl: 10h0m0s

To create these two roles you can execute:

$ gravity resource create administrator.yaml
$ gravity resource create developer.yaml

To view all currently available roles:

$ gravity resource get role

To delete the developer role:

$ gravity resource delete role developer

Configuring Users & Tokens

Below is an example of a resource file that creates a user called user.yaml.

kind: user
version: v2
  name: "[email protected]"
  # "agent" type means this user is only authorized to access the Cluster
  # using the API key (token) and not using the web UI
  type: agent
  roles: ["developer"]

Create the user by executing gravity resource:

$ gravity resource create user.yaml

A token can is assigned to this user by using the following resource file called token.yaml:

kind: token
version: v2
   name: xxxyyyzzz
   user: "[email protected]"

Create the token by executing gravity resource:

$ gravity resource create token.yaml

To view available users and a user's tokens:

$ gravity resource get user
$ gravity resource get token [email protected]

Example: Provisioning A Cluster Admin User

The example below shows how to create an admin user for a Cluster. Save the user definition into a YAML file:

# admin.yaml
kind: user
version: v2
  name: "[email protected]"
  type: "admin"
  password: "Passw0rd!"
  roles: ["@teleadmin"]

The password will be encrypted with bcrypt prior to being saved into the database. Note the role @teleadmin - this is a built-in system role for the Cluster administrators.

To create the user from the YAML above, execute the following command on one of the Cluster nodes:

$ gravity resource create admin.yaml

The new user can now log into the Cluster via the Web UI with the user credentials created above.

Username and Password Restrictions

Usernames should be composed of characters, hyphens, the at symbol and dots. Passwords must be between 6 and 128 characters long.

Configuring a GitHub Connector

Gravity supports authentication and authorization via GitHub. To configure it, create a YAML file with the resource spec based on the following example:

kind: github
version: v3
  name: example
  # Github OAuth app client ID
  client_id: <client-id>
  # Github OAuth app client secret
  client_secret: <client-secret>
  # Github will make a callback to this URL after successful authentication
  # Cluster-url is the address the Cluster UI is reachable at
  redirect_url: "https://<Cluster-url>/portalapi/v1/github/callback"
  # connector display name that will be appended to the title of "Login with"
  # button on the Cluster login screen so it will say "Login with Github"
  display: Github
  # mapping of Github team memberships to Gravity Cluster roles
    - organization: example
      team: admins
        - "@teleadmin"

Create the connector:

$ gravity resource create github.yaml

Once the connector has been created, the Cluster login screen will start presenting "Login with GitHub" button.


When going through the Github authentication flow for the first time, the application must be granted the access to all organizations that are present in the "teams to logins" mapping, otherwise Gravity will not be able to determine team memberships for these organizations.

To view configured GitHub connectors:

$ gravity resource get github

To remove a GitHub connector:

$ gravity resource rm github example

Configuring OpenID Connect

Enterprise Only Version Warning

The ability to configure an OIDC Connector is only available in Gravity Enterprise.

A Gravity Cluster can be configured to authenticate users using an OpenID Connect (OIDC) provider such as Auth0, Okta and others.

A resource file in YAML format creates the connector. Below is an example of an OIDC resource for provider "Auth0" called oidc.yaml:

kind: oidc
version: v2
  name: auth0
  redirect_url: "https://gravity-url/portalapi/v1/oidc/callback"
  client_id: <client id>
  client_secret: <client secret>
  issuer_url: ""
  scope: [roles]
    - {claim: "roles", value: "gravitational/admins", roles: ["@teleadmin"]}


For Auth0 the "OIDC Conformant" setting should be off in Advanced Setting -> OAuth or Claims will not populate properly

Add this connector to the Cluster:

$ gravity resource create oidc.yaml

To list the installed connectors:

$ gravity resource get oidc

To remove the connector auth0:

$ gravity resource rm oidc auth0

Example: Google OIDC Connector

Enterprise Only Version Warning

The ability to configure a Google OIDC connector is only available in Gravity Enterprise.

Here's an example of the OIDC connector that uses Google for authentication:

kind: oidc
version: v2
  name: google
  redirect_url: "https://ops-advertise-url/portalapi/v1/oidc/callback"
  client_id: <client id>
  client_secret: <client secret>
  scope: [email]
    - {claim: "hd", value: "", roles: ["@teleadmin"]}

The hd scope contains the hosted Google suite domain of the user so in the above example, any user who belongs to the "" domain will be allowed to log in and granted the admin role.


The user must belong to a hosted domain, otherwise the hd claim will not be populated.

Configuring SAML Connector

Enterprise Only Version Warning

The ability to configure a SAML Connector is only available in Gravity Enterprise.

Gravity supports authentication and authorization via SAML providers. To configure it, create a YAML file with the resource spec based on the following example:

kind: saml
version: v2
  name: okta
  # SAML provider will make a callback to this URL after successful authentication
  # Cluster-url is the address the Cluster UI is reachable at
  acs: https://<Cluster-url>/portalapi/v1/saml/callback
  # mapping of SAML attributes to Gravity roles
    - name: groups
      value: admins
        - @teleadmin
  # connector display name that will be appended to the title of "Login with"
  # button on the Cluster login screen so it will say "Login with Okta"
  display: Okta
  # SAML app metadata in XML format downloaded from SAML provider
  entity_descriptor: |


For an example of configuring a SAML application with Okta take a look at the following guide: SSH Authentication With Okta.

Create the connector:

$ gravity resource create saml.yaml

To view configured SAML connectors:

$ gravity resource get saml

To remove a SAML connector:

$ gravity resource rm saml okta

Cluster Authentication Gateway

!!! warning "Version Warning":

Authentication gateway resource is supported starting Gravity version `5.5.0`.

The Cluster authentication gateway handles the authentication and authorization and uses the following resource:

kind: authgateway
version: v1
  # Connection throttling settings
    # Max number of simultaneous connections
    max_connections: 1000
    # Max number of simultaneously connected users
    max_users: 250
  # Cluster authentication preferences
    # Auth type, can be "local", "oidc", "saml" or "github"
    type: oidc
    # Second factor auth type, can be "off", "otp" or "u2f"
    second_factor: otp
    # Default auth connector name
    connector_name: google
  # Determines if SSH sessions to Cluster nodes are forcefully terminated
  # after no activity from a client, for example "30m", "1h", "1h30m"
  client_idle_timeout: never
  # Determines if the clients will be forcefully disconnected when their
  # certificates expire in the middle of an active SSH session
  disconnect_expired_cert: false
  # DNS name that applies to all SSH, Kubernetes and web proxy endpoints
  # DNS name of the gateway SSH proxy endpoint, overrides "public_addr"
  # DNS name of the gateway Kubernetes proxy endpoint, overrides "public_addr"
  # DNS name of the gateway web proxy endpoint, overrides "public_addr"

To update authentication gateway configuration, run:

$ gravity resource create gateway.yaml


The gravity-site pods will be restarted upon resource creation in order for the new settings to take effect, so the Cluster management UI / API will become briefly unavailable.

When authentication gateway resource is created, only settings that were explicitly set are applied to the current configuration. For example, to only limit the maximum number of connections, you can create the following resource:

kind: authgateway
version: v1
    max_conections: 1500

The following command will display current authentication gateway configuration:

$ gravity resource get authgateway

Cluster Authentication Preference

Deprecation warning

Cluster authentication preference resource is obsolete starting Gravity version 5.5.0 and will be removed in a future version. Please use Authentication Gateway resource instead.

Cluster authentication preference resource allows to configure method of authentication users will use when logging into a Gravity Cluster.

The resource has the following format:

kind: Cluster_auth_preference
version: v2
  name: auth-oidc
  # preferred auth type, can be "local" (to authenticate against
  # local users database) or "oidc"
  type: oidc
  # second-factor auth type, can be "off" or "otp"
  second_factor: otp
  # default authentication connector to use for tele login
  connector_name: google

By default the following authentication method is configured:

To update authentication preference, for example to allow local users to log into Gravity Hub without second-factor, define the following resource:

kind: Cluster_auth_preference
version: v2
  name: auth-local
  type: local
  second_factor: "off"

Create it:

$ gravity resource create auth.yaml


Make sure to configure a proper OIDC connector when using "oidc" authentication type.

To view the currently configured authentication preference:

$ gravity resource get Cluster_auth_preference
Type      ConnectorName     SecondFactor
----      -------------     ------------
local                       off

Log Forwarders

Every Gravity Cluster is automatically set up to aggregate the logs from all running containers. By default, the logs are kept inside the Cluster but they can be configured to be shipped to a remote log collector such as a rsyslog server.

Below is a sample resource file called forwarder.yaml that creates a log forward:

kind: logforwarder
version: v2
   name: forwarder1
   protocol: udp

The protocol field is optional and defaults to tcp. Create the log forwarder:

$ gravity resource create forwarder.yaml

To view currently configured log forwarders, run:

$ gravity resource get logforwarders

To delete a log forwarder:

$ gravity resource rm logforwarder forwarder1

TLS Key Pair

Gravity Cluster Web UI, (Gravity Hub for Enterprise Users) and API TLS key pair can be configured using tlskeypair resource.

kind: tlskeypair
version: v2
  name: keypair
  private_key: |
  cert: |

Certificate chain

cert section should include all intermediate certificate PEM blocks concatenated to function properly!

To update the key pair:

$ gravity resource create tlskeypair.yaml

To view the currently configured key pair:

$ gravity resource get tls

To delete a TLS key pair (in this case default self-signed TLS key pair will be used instead):

$ gravity resource rm tls keypair

Monitoring and Alerts

See the Cluster Monitoring section about details on how to configure monitoring and alerts.

Runtime Environment Variables

In a Gravity Cluster, each node is running a Master Container (called "Planet") that hosts Kubernetes. All services (including Kubernetes native services like API server or kubelet) execute within the predefined environment (set up during installation or update). The RuntimeEnvironment allows you to make changes to the runtime environment, i.e. introduce new environment variables like HTTP_PROXY.

To add a new environment variable, HTTP_PROXY, create a file with following contents:

kind: RuntimeEnvironment
version: v1
    HTTP_PROXY: ""

To install a Cluster with the new runtime environment, specify the resources file as an argument to the install command:

$ sudo gravity install --cluster=<cluster-name> --config=envars.yaml

On an installed Cluster, create the resource with:

$ sudo gravity resource create -f envars.yaml
Updating Cluster runtime environment requires restart of runtime containers on all nodes.
The operation might take several minutes to complete depending on the Cluster size.

The operation will start automatically once you approve it.
If you want to review the operation plan first or execute it manually step by step,
run the operation in manual mode by specifying '--manual' flag.

Are you sure?
confirm (yes/no):

Without additional parameters, the operation is executed automatically, but can be placed into manual mode with the specification of --manual | -m flag to the gravity resource command:

$ sudo gravity resource create -f envars.yaml --manual

This will allow you to control every aspect of the operation as it executes. See Managing Operations for more details.

To view the currently configured runtime environment variables:

$ gravity resource get runtimeenvironment

To remove the configured runtime environment variables, run:

$ gravity resource rm runtimeenvironment


Adding or removing Cluster runtime environment variables is disruptive as it necessitates the restart of runtime containers on each Cluster node. Take this into account and plan each update accordingly.

Trusted Clusters (Enterprise)

Enterprise Only Version Working

Gravity Hub and Trusted Clusters are only supported in Gravity Enterprise. Support for Trusted Clusters is available since Gravity version 5.0.0-alpha.5.

Trusted Clusters is a concept for connecting standalone Gravity Clusters to a Gravity Hub. It brings the following advantages:

To configure a Trusted Cluster create the following resource:

kind: trusted_cluster
version: v2
  enabled: true
  pull_updates: true
  token: c523fd0961be71a45ceed81bdfb61b859da8963e2d9d7befb474e47d6040dbb5
  tunnel_addr: ""
  web_proxy_addr: ""
  - remote: "@teleadmin"
    local: ["@teleadmin"]

Let's go over the resource fields:

Role mapping

If not explicitly specified, the default role mapping will only map the remote admin role @teleadmin to the local admin role @teleadmin as shown in the example above. See Teleport documentation on Trusted Clusters RBAC for information about configuring role mapping.

Create the Trusted Cluster:

$ gravity resource create trustedCluster.yaml

View the currently configured Trusted Cluster:

$ gravity resource get trusted_Cluster
Name                Enabled     Pull Updates     Reverse Tunnel Address    Proxy Address
----                -------     ------------     ----------------------    -------------     true        true   

Once the Cluster has been created, the reverse tunnel status can be viewed and managed using gravity tunnel shortcut commands:

$ gravity tunnel status
Gravity Hub       Status   enabled

$ gravity tunnel disable
Gravity Hub       Status   disabled

$ gravity tunnel enable
Gravity Hub       Status   enabled

To disconnect the Cluster Gravity Hub, remove the Trusted Cluster:

$ gravity resource rm trustedCluster
Trusted Cluster "" has been deleted

Customize Number of DNS instances on workers

Gravity ships a default DNS configuration that should be appropriate for most environments, that scales based on the number of CPU cores and nodes within the cluster.

The scaling configuration can be customized by replacing the autoscaler configmap with the desired configuration.

kubectl apply -f - <<EOF
kind: ConfigMap
apiVersion: v1
  name: autoscaler-coredns-worker
  namespace: kube-system
  annotations: "true"
  linear: |-
      "coresPerReplica": 4,
      "nodesPerReplica": 1,
      "min": 9,
      "preventSinglePointFailure": true

The annotation indicates to gravity that the configuration has been overwritten, and that cluster upgrades should not reset the configuration to default.


Gravity uses the cluster-proportional-autoscaler to scale the number of DNS instances on workers. For more information on how to configure the autoscaler, please see the cluster-proportional-autoscaler docs for information.

Gravity Enterprise

Gravity Enterprise enhances Gravity Community, the open-source Kubernetes packaging solution, to meet security and compliance requirements. It is trusted by some of the largest enterprises in software, finance, healthcare, security, telecom, government, and other industries.

Demo Gravity Enterprise

Gravity Community

Gravity Community is an upstream Kubernetes packaging solution that takes the drama out of on-premise deployments. Gravity Community is open-source software that anyone can download and install for free.

Download Gravity Community