You were just given an Uncloud cluster. Now what? This howto explains what Uncloud is, why we think its needed and some pointers other documentation. At the end you’ll find a FAQ like section.

We very much want Uncloud to profit from our use, so our intention is to upstream as much documentation as possible. Also see my personal journey with Uncloud; those articles are also in the process of being integrated with the Uncloud documentation.

Note that your using a small fork called uncloudplus, which is Uncloud + a handful “ease of use” changes included.

Currently we assume the following split in responsibility:

  • We will upgrade the uncloud machines.
  • There are no default backups, we can help here of course.
  • You are in control (and responsible) of the images.
  • Images should be kept up to date (regenerated, and re-pushed).

What is Uncloud?

Uncloud is “remote Docker compose”. It allows you to run anything you want to run with potentially web access (HTTP/HTTPS) on a machine you “own”. Uncloud can cluster multiple machines and share load between them. As you are in control of the Uncloud cluster you can even add a VPS machine running on the internet to your Science Uncloud cluster - there are no restriction on that.

When clustering, the power of Uncloud becomes more apparent. If you only have a single machine it behaves more like Docker compose.

If you are familiar with the juggernaut in this space: Kubernetes, then Uncloud is completely different. K8S is declarative: you define how things should run, the cluster figures out how to accomplish that. If this works, it’s beautiful, but K8S are highly dynamic and debugging and upgrading can be a nightmare.

Uncloud is imperative; you give a command and it gets executed, there is no control plane that make things happen automagically. The cluster is also much more static, aiding in debugging and upgrades consists of just upgrading the software.

Why Uncloud?

Uncloud fills a niche where you need something that we don’t provide a service for; historically this would mean that we provision a machine and make it work in a way what works for you. This has benefits and downsides. A benefit is that when it works, we do all maintenance and keep it working. A downside is that this is very much a hands-on experience which usually requires you to come into the office and almost pair program the machine with us. Putting you in control allows for much faster throughput, less work for everybody and also less control from us.

As alluded above other solutions exist, but are overkill or just hard to manage. I.e K8S, K3S, Nomad (unsure about it’s future after the IBM takeover). Uncloud is just small and simple. Things like Kamal occupy the same space, but Uncloud is more mature and more polished.

Getting Started

The easiest way to get started is to create a local Docker compose setup and get that working first. Once you’re happy with it you can deploy it to the cluster. This should work, but there are some differences and see the support matrix.

Most importantly you don’t need to open up ports, all ports for all services are reacheable in the internal uncloud network. Only web access from the outside will require an x-ports (see the extensions, as linked above).

Cluster

An Uncloud cluster start with a single machine, but can be extended by us (or by you) with more machines - even external VPS machines can be added to a cluster.

Initially a cluster consists:

  • of a machine named ‘uncloudN`, where N is a number, with (this can be enlarged)
    • 2 CPUs
    • 2 GB RAM
    • 50 GB Disk
  • a group name un-xxxx that control cluster access.
  • are all located in the 174.131.138.0/24 network.
  • SSH access is prohibited from the Internet (See how to use SSH.
  • the lilo machine can access your cluster (via SSH).
  • a single user uc is configured as the Uncloud-access-user.
  • is running a bunch of un-services that we start.

You can connect to the cluster with uc --context uc@uncloudN.vm.science.ru.nl or you should have received a config file that simplifies this a bit in the form of some YAML:

current_context: acluster
contexts:
  acluster:
    connections:
      - ssh: uc@uncloud10.vm.science.ru.nl
        machine_id: 5f427ff27f79ae9cb60b2eb0991b880e

This needs to be stored in the correct place (also see), then you can use uc and it will figure out how to connect.

Access

The cluster access is determined by the public SSH keys that are allowed for the uc user. This is done via the unkey service. That pulls public keys and configures them for this uc user.

Any member of the un-xxxx group will have access to the cluster; you as a cluster owner are able to add/remove user from the group in DIY.

The public keys used are the keys you have registered in DIY, of the type “login”.

If you stop the unkey service (uc remove unkey) this updating will cease, but can be restarted by using the compose.yaml from the container/unkey repository.

All our machine have the uc binary installed.

Images

Our gitlab can be used to create and push images to. An example repository that does this is our images repository, that also features an automatic build and push when ever a tag is pushed.

Image pruning

Docker images can fill up diskspace, if you want to docker prune automatically, run the unprune service from the container repository with cd unprune; uc deploy -y.

Backups

Currently it is your responsibility to create backups and store them somewhere safe. But we can provide access to S3 buckets where kopia can store your data.

Private Registries

If you have a private registry you need to locally do a docker login. The credentials are forwarded to the cluster.

RU Specific Things

import ru

If you want to block outside traffic you can do so as follows. Our Caddy deployment adds a match list you can use inside your x-caddy config, for example the following:

I.e.

x-caddy: |
  https://myurl.u.science.ru.nl https://myurl.nl {
    import ru

    handle @ru {
      reverse_proxy {{upstreams 8080}} {
              import common_proxy
      }
    }
    handle {
              respond "Blocking non-RU IP addresses."
    }
    log
  }

Also see https://uncloud.run/docs/concepts/ingress/publishing-services.

Images and (Example) Compose Files

All images prefixed with un are C&CZ service images that may run in your cluster. In https://gitlab.science.ru.nl/cncz/sys/container you find the compose.yaml service deploys for various services. In https://gitlab.science.ru.nl/cncz/sys/image there are several images you can use as well

Unfileserver

On on this images is unfileserver for instance. unfileserver is a super simple HTTP server that serves files from /static and listens on port 3000. This can be used to serve static content from.

Unprune

Unprune is a small image and deployment that prunes orphaned images and volumes every 24 hours.

UC image

We have an image with the Uncloud client uc which you can use in GitLab pipeline to push directly to your cluster. For this a private key must also be available to uc and access to the cluster.

The image can be found here: registry.science.ru.nl/cncz/sys/image/uc:latest (there are also image version tags if you want to clamp to a specific image version.

Jump host

You can’t directly reach cluster via SSH, this needs a JumpHost setup. Easiest is to put the following snippet in your ~/.ssh/config:

Host uncloud*
    ProxyJump lilo.science.ru.nl

To always use lilo as your cluster’s jump host.

DNS and Let’s Encrypt

If you control your own DNS and want to have a vanity URL for your deployment, you need to do the following, asssuming your cluster is named “web”, and this compose.yaml:

services:
  homepage:
    image: alpine:latest
    x-ports:
      - my.vanity.url.org:3000/https
  1. Create a CNAME from your URL to the internal name of this deployment: homepage.web.u.science.ru.nl: my.vanity.url.org IN CNAME homepage.web.u.science.ru.nl.
  2. Make sure the x-ports section is correct.

Note: this CNAME should exist before you deploy (there is no harm if it exists), otherwise you’ll get timeouts from Let’s Encrypt which fails to resolve the DNS.