Skip to content

Latest commit

 

History

History
164 lines (103 loc) · 4.91 KB

GETTING-STARTED.md

File metadata and controls

164 lines (103 loc) · 4.91 KB
Raw

Getting Started

1. Requirement

✓ Kubernetes Version

Version ≥ 1.19

COSMO is targeting to run on any Kubernetes distribution.

🌐 Networking & DNS

COSMO uses Traefik Ingress Controller and Host-header routing for each Workspaces.

Configure a wildcard-host domain record like *.YOUR_DOMAIN.com in your name server targeting to your Load Balancer for Traefik Proxy.

For example in Amazon EKS using AWS Load Balancer Controller and Route53 for a name server

💾 Volumes

To persist workspace data, each workspace templates should include a Persistent Volume Claim.

You need to configure Dynamic Provisioning in Kubernetes, which does not require a Persistent Volume manually created by administrator.

2. Install COSMO on your Kubernetes Cluster

Confirm followings before installation.

  • kubectl and helm is installed in PATH.
  • kubectl current context to the cluster where you install COSMO.

2-1. Install cert-manager

COSMO requires a lot of TLS certificates.

The easiest way to prepare certificates is to use cert-manager (>=v1.0.0)

See the offical install docs https://cert-manager.io/docs/installation/

kubectl apply -f https://github.com/jetstack/cert-manager/releases/latest/download/cert-manager.yaml

2-2. Install COSMO

Add helm repo

helm repo add cosmo https://cosmo-workspace.github.io/charts

Install cosmo

WORKSPACE_DOMAIN=YOUR_DOMAIN.com

# When you configured TLS cert '*.YOURDOMAIN.com' for traefik
helm upgrade --install -n cosmo-system --create-namespace cosmo-controller-manager cosmo/cosmo-controller-manager \
  --set domain=$WORKSPACE_DOMAIN

# When you did't configured TLS cert '*.YOURDOMAIN.com' for traefik
helm upgrade --install -n cosmo-system --create-namespace cosmo-controller-manager cosmo/cosmo-controller-manager \
  --set domain=$WORKSPACE_DOMAIN \
  --set protocol=http

Output:

### Example Output
Release "cosmo" does not exist. Installing it now.
NAME: cosmo
LAST DEPLOYED: Tue Jul 18 02:37:15 2023
NAMESPACE: cosmo-system
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
COSMO is installed!

* Your Environment Infomation
  +-----------------------+------------------------------------------------------------
  | DOMAIN                | *.YOUR_DOMAIN.com
  | DASHBOARD_URL         | https://dashboard.YOUR_DOMAIN.com/#/signin
  | WORKSPACE_URLBase     | https://{{NETRULE}}-{{WORKSPACE}}-{{USER}}.YOUR_DOMAIN.com
  +-----------------------+------------------------------------------------------------

Now access COSMO Dashboard URL you configured from your browser.

💡 See charts repository for more information on helm installation options.

2-3. Install cosmoctl

Download binary from latest release and extract it into PATH.

3. Create first User

Use cosmoctl to create first User.

cosmoctl user create admin --privileged

Output:

### Example Output
Successfully created user admin
Default password: DEFAULT_PASSWORD

Access the dashboard with a browser and login as admin with the output password.

Now you are ready to use COSMO 🚀

4. Create example Template

However there is still NO Template. Create example Templates.

kubectl create -f https://raw.githubusercontent.com/cosmo-workspace/cosmo/main/example/workspaces/code-server.yaml

Now you are ready to use Template code-server-example 🙌

5. Create Workspace

From browser, create a example workspace with created Template.

get-start-demo1.mp4

6. Cleanup

Uninstall COSMO.

helm uninstall -n cosmo-system cosmo

Uninstall COSMO CRD.

This will remove all Workspaces and Templates.

kubectl delete -k https://github.com/cosmo-workspace/cosmo/config/crd/