This is the multi-page printable view of this section. Click here to print.
Faros strives to be the best platform as a service for your remote Kubernetes clusters. Where we can do a lot of things, we will structure our documentation around core features. If you have any questions, please reach out to us at Contacts.
For now Faros is predominantly a CLI tool, so we will focus on the CLI documentation. We will also provide some examples of how to use the CLI tool.
Overall Faros is built, so you can build your own platforms on top of it. While we understand that it is not for everyone, we believe that it can be a great tool for those who want to build their own platforms.
In addition we will be working for some core features “out of the box” that can be used by everyone. And hope with time we will be able to provide more features that can be used by everyone.
Faros is distributes control-plane for Kubernetes-like control planes.
For now we are focusing on the following use-case:
What is it good for?: You have k3s, k0s, k8s, or any other kubernetes cluster and you want to access it from your local machine without exposing it to the internet.
What is it not yet good for?: We will enable more features in the future that will make it more useful for other use-cases. In example 0 trust access to the cluster, or multi-tenancy where we can expose only certain namespaces to certain users. This allows you to share your cluster with others without giving them full access to the cluster.
To get started, check out the following sections:
Faros CLI can be used as standalone or kubectl plugin. It is a tool that allows you to interact with Faros API.
kubectl is installed. If not, refer to the official Kubernetes documentation for installation guidance.krew, the kubectl plugin manager, following the official krew documentation.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
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.
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.
Check the supported APIs using the command:
kubectl api-resources
Once you have installed the Faros CLI, you can create a workspace to group resources together under a virtual cluster-like environment. Each workspace contains its own resources, such as namespaces, service accounts, roles, roleBindings, secrets, and configMaps.
kubectl get ws
kubectl faros ws tree
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.
kubectl get ws
# Example output
NAME TYPE REGION PHASE URL AGE
clusters faros Ready https://kcp.faros.sh:443/clusters/exampleorg:clusters 7s
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.
Once you have installed the Faros CLI, you can create a workspace to group resources together under a virtual cluster-like environment. Each workspace contains its own resources, such as namespaces, service accounts, roles, roleBindings, secrets, and configMaps.
kubectl get ws
kubectl faros ws tree
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.
kubectl get ws
# Example output
NAME TYPE REGION PHASE URL AGE
clusters faros Ready https://kcp.faros.sh:443/clusters/exampleorg:clusters 7s
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.
This is a placeholder page that shows you how to use this template site.
For many projects, users may not need much information beyond the information in the Overview, so this section is optional. However if there are areas where your users will need a more detailed understanding of a given term or feature in order to do anything useful with your project (or to not make mistakes when using it) put that information in this section. For example, you may want to add some conceptual pages if you have a large project with many components and a complex architecture.
Remember to focus on what the user needs to know, not just what you think is interesting about your project! If they don’t need to understand your original design decisions to use or contribute to the project, don’t put them in, or include your design docs in your repo and link to them. Similarly, most users will probably need to know more about how features work when in use rather than how they are implemented. Consider a separate architecture page for more detailed implementation and system design information that potential project contributors can consult.
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.
TBC
Mounts in Faros allows you to mount a remote cluster into your local workspace for easier management and access to resources. This feature is useful for managing multiple clusters and resources across different environments.
TBC
This is a placeholder page that shows you how to use this template site.
Do you have any example applications or code for your users in your repo or elsewhere? Link to your examples here.
Top use Swagger Authentication feature use the following swagger instance: https://api.faros.sh/swagger/
We are working on more smooth integration with the API documentation.
When authenticating, use ClientID: faros and mark all scopes.