Getting Started

• 1: Install CLI
• 2: Create a Workspace
• 3: Mount a Cluster

1 - Install CLI

Prerequisites:

• Ensure kubectl is installed. If not, refer to the official Kubernetes documentation for installation guidance.
• Install krew, the kubectl plugin manager, following the official krew documentation.

Plugin Installation:

Execute the commands below to add the Faros plugin and install it:

kubectl krew index add faros https://github.com/faroshq/krew-index.git
kubectl krew install faros/faros

To update the plugin, run:

kubectl krew upgrade

Understanding Workspaces

Workspaces in Faros are akin to Kubernetes namespaces, but with enhanced functionality. They are designed to group resources together under a virtual cluster-like environment, without being actual clusters. Each workspace contains its own resources, such as namespaces, service accounts, roles, roleBindings, secrets, and configMaps.

More information about workspaces can be found here.

Setting Up and Managing Workspaces

kubectl faros login

Once logged in, create and manage new workspaces similarly to how you would manage a regular Kubernetes cluster.

Users can be invited via their email, associated with their GitHub accounts, using the following role binding template:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: workspace-admin
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin
subjects:
- apiGroup: rbac.authorization.k8s.io
  kind: User
  name: faros-sso-{email}

We are working on a feature to expose workspaces, you have access to, via the Faros CLI. This will allow you to manage workspace access and interact with them via the CLI.

For now if you shared a workspace with someone, they will have to access by changing the context in their kubectl configuration.

Explore Kubernetes APIs

Check the supported APIs using the command:

kubectl api-resources

2 - Create a Workspace

Prerequisites:

• Ensure you have installed the Faros CLI. If not, refer to the official Faros documentation.

Step-by-Step Workspace Creation

Check Current Hierarchy Level Workspaces:

kubectl get ws

View Full Hierarchy Tree:

kubectl faros ws tree

Create the First Workspace Named clusters:

kubectl faros ws create clusters
# Confirmation of creation and readiness
Workspace "clusters" (type root:faros) created. Waiting for it to be ready...
Workspace "clusters" (type root:faros) is ready to use.

Check the Newly Created Workspace:

kubectl get ws
# Example output
NAME       TYPE    REGION   PHASE   URL                                                     AGE
clusters   faros            Ready   https://kcp.faros.sh:443/clusters/exampleorg:clusters   7s

Creating Nested Workspaces & Navigating

Navigate Inside the Workspace:

kubectl faros ws use clusters
kubectl faros ws create prod

Return to Root Workspace:

kubectl faros ws use :

Display Full Workspace Hierarchy:

kubectl faros ws tree
kubectl ws tree
# Example output
.
└── ixn3tjgtr9bb
    └── clusters
        └── prod

How each workspace is structured and managed is up to you. You can create as many workspaces as you need, and nest them as required.

3 - Mount a Cluster

Prerequisites:

• Ensure you have installed the Faros CLI. If not, refer to the official Faros documentation.

Step-by-Step Workspace Creation

Check Current Hierarchy Level Workspaces:

kubectl get ws

View Full Hierarchy Tree:

kubectl faros ws tree

Create the First Workspace Named clusters:

kubectl faros ws create clusters
# Confirmation of creation and readiness
Workspace "clusters" (type root:faros) created. Waiting for it to be ready...
Workspace "clusters" (type root:faros) is ready to use.

Check the Newly Created Workspace:

kubectl get ws
# Example output
NAME       TYPE    REGION   PHASE   URL                                                     AGE
clusters   faros            Ready   https://kcp.faros.sh:443/clusters/exampleorg:clusters   7s

Creating Nested Workspaces & Navigating

Navigate Inside the Workspace:

kubectl faros ws use clusters
kubectl faros ws create prod

Return to Root Workspace:

kubectl faros ws use :

Display Full Workspace Hierarchy:

kubectl faros ws tree
kubectl ws tree
# Example output
.
└── ixn3tjgtr9bb
    └── clusters
        └── prod

How each workspace is structured and managed is up to you. You can create as many workspaces as you need, and nest them as required.

Mount the Remote Cluster Locally: If you have access to the remote cluster from your local machine:

kubectl faros mount prod --remote-kubeconfig=kind.kubeconfig

After mounting, using kubectl faros ws use prod will give you access to the remote cluster.

Mount the Remote Cluster from a Remote Machine: If the remote cluster is not accessible from your local machine:

kubectl faros mount prod -w prod

You’ll need to deploy resources manually to the remote cluster:

# Get resources to deploy
kubectl get configmap prod-resources -o jsonpath='{.data.resources}' > prod-resources.yaml

# Deploy resources
kubectl apply -f prod-resources.yaml --kubeconfig <your-kubeconfig>

# Wait for the cluster to accept the mount
kubectl get KubeCluster -w

Verify All Mounted Clusters:

kubectl faros ws tree -f
.
└── ixn3tjgtr9bb
    └── ixn3tjgtr9bb:clusters
        └── ixn3tjgtr9bb:clusters:prod

With these steps, you can mount any remote cluster to your Faros workspace, allowing for streamlined management and access through a single command like

kubectl faros ws use ixn3tjgtr9bb:clusters:prod

or by navigating the workspace hierarchy.