features.org

Features

Environment

Is the container image that is used for providing a shared environment with a shared terminal session and lots of useful utilities. It features Doom, but also packages Spacemacs, with custom shared configurations. It also contains Humacs, some extra configuration on top of Doom, maintained by ii.

Environment is deployed as a container image into the cluster as a StatefulSet, which is accessed as a Pod.

Full instance SSH access

The instances have SSH enabled and load your and your guests GitHub SSH keys into the authorized_keys file. You can SSH in as the root or ii user.

Docker access

Access to the full socket is available in /var/run/docker.sock or through the docker cli.

host-shell

When working in Pair, occiasionally an escape from the container is needed for a task. To get a shell on the Instance host system, simply use the host-shell program (provided by Environment)

It also supports inline execution of the commands, if dropping into a shell is not useful:

host-shell <my command>

Host filesystem

The filesystem of the host machine is mounted inside the Environment Pod under /var/run/host

ls /var/run/host

Instance naming (admin only)

Admins have the ability to custom name instances.

Automatic exposing of services inside of Environment

Whenever a TCP or UDP service is bound on all interfaces, a Service is exposed on the $SHARINGIO_PAIR_LOAD_BALANCER_IP. TCP services will also be allocated an Ingress, based on the DNS name of the instance and process name. Allocated subdomain names can be overridden by declaring a value for $SHARINGIO_PAIR_SET_HOSTNAME. Services with duplicate names will be appended with their port, to avoid duplication.

Note: avoid labeling Service and Ingress resources with io.sharing.pair/managed=true in the namespace of your username to avoid conflict.

(functionality provided by environment-exporter and environment-exposer)

.sharing.io/init

Each repo can have a .sharing.io/init script to initialize the project.

An init script can do many things, such as:

• installing packages
• bringing up Tilt
• writing .env files
• creating tmate windows
• bringing up services
• deploying Kubernetes apps

Some examples include:

• https://github.com/sharingio/pair/blob/master/.sharing.io/init
• https://github.com/sharingio/.sharing.io/blob/master/.sharing.io/init
• https://github.com/cncf-infra/prow-config/blob/master/.sharing.io/init
• https://github.com/Safe-Surfer/safesurfer-powerdns/blob/master/.sharing.io/init
• https://gitlab.com/flattrack/flattrack/-/blob/master/.sharing.io/init

Personal .sharing.io

If the sharingio/.sharing.io repo is forked into your repos, it will be run instead of the default. It provides the same functionality as other .sharing.io/init scripts.

Full instance DNS control

DNS is mapped to {{ InstanceName }}.{{ PairHost }} (e.g: myinstance.pair.sharing.io).

As External-DNS also runs on each instance. All instances have a user-manageable DNSEndpoint in the powerdns namespace, which will be named after the instance. Any DNS record at or below the domain name.

Wildcard LetsEncrypt TLS cert

A wildcard DNS record is available to be used manually. If sync the wildcard cert, you’ll need to label the namespace with cert-manager-tls=sync:

kubectl label ns {{ MyNamespace }} cert-manager-tls=sync

This can also be included in the .sharing.io/init script.

Public HTML

With each instance, the ~/public_html folder is accessible from the www subdomain of the instance. This is served using safesurfer/go-http-server, configurable through the HelmRelease of public-html.

Transparent home folder

The home folder on the host machine is the exact folder as inside of the environment.

Init scripts are re-runable

Instances are initialised using the sharingio/.sharing.io repo. The scripts can be rerun with

. <(sudo cat /var/run/host/root/.sharing-io-pair-init.env)
~/.sharing.io/cluster-api/postKubeadmCommands.sh

Structured repo cloning

When an instance comes up, the repos are cloned like {{ Org }}.{{ Project }}. For example, if I set https://github.com/sharingio/pair as a repo, it will be clone to ~/sharingio/pair.

The same kind of cloning can be invoked with git-clone-structured.

Additional nodes

When creating an instance, admins will be presented with the option to create instances with up to three non-controlplane nodes.

Disable GitHub token

Whilst the feature of having the GitHub token is useful, sometimes folks may not want to pass their token (with what ever permissions) through.

This is the way to make your instance the most secure.

Max instances

When deploying Pair, admins are able to set a max number of instances per user account (.Values.maxInstancesForNonAdmins).

Environment variables

Various environment variables are available inside of the pairing environment:

Name	Description
SHARINGIO_PAIR_NAME	The name of the Pair instance
SHARINGIO_PAIR_BASE_DNS_NAME	The base domain name of the Pair instance
SHARINGIO_USER	The username of the GitHub user who created the instance
SHARINGIO_PAIR_GUEST_NAMES	The GitHub usernames of the guests for the instance
SHARINGIO_PAIR_LOAD_BALANCER_IP	The LoadBalancer IP for the Pair instance
GITHUB_TOKEN	The GitHub token of the GitHub user who created the instance

Misc

• helm-operator: manage Helm charts declaratively
• registry-creds-system: enable syncing of secrets for registries
• local-path-provisioner: provide a CSI pvc
• metallb: allows Services to have a bare metal IP address (BGP, l2)