ucloud-docs/README.md
2019-10-10 18:27:42 +02:00

359 lines
7.8 KiB
Markdown

## ucloud docs
Are stored in lektor/ and use
[lektor](https://www.getlektor.com/).
## ucloud flows
Stuff that we want to do with ucloud
### General
* Colour
* blue: part of infrastructure/not maintained by ucloud
* green: ucloud component that works and is tested
* black: undefined
* red: ucloud component that we need to develop on
### Ucloud Infrastructure
```graphviz
digraph{
cephcluster [ label="Ceph cluster" shape="oval" color="blue" ];
ceph1 [ color="blue"]
ceph2 [ color="blue"]
ceph3 [ color="blue"]
uotp [ label="utop token service"]
etcd
ucloudnet [ label="ucloud-network" color="red"]
ucloudsomething->cephcluster [ label=" Link/copy image "]
cephcluster -> { ceph1, ceph2, ceph3}
}
```
### VM Create
```graphviz
digraph {
subgraph g1 {
node [ shape="box"]
user [ label="User" shape="circle"]
user -> cli [ label=" uses "]
cli [ label="ucloud-cli" color="green"]
api [ label="ucloud-api" color="green"]
cli -> api [ label=" To Create/Start VM [1]"];
api -> uotp [label="Verify token [2]" dir="both"]
api -> etcd [label="Create (VM Entry and \nA Request to Schedule VM) [3]"];
}
subgraph cluster_otp {
uotp [shape="diamond" label="ungleich otp"]
}
subgraph cluster_etcd {
etcd
}
}
```
### VM Scheduling
```graphviz
digraph {
node [ shape="box"]
subgraph cluster_etcd {
etcd
}
etcd -> scheduler [label=" Fetch VM Scheduling Request [5]"]
subgraph cluster_scheduler {
scheduler -> scheduler [ label=" Find suitable Host [6]"]
}
scheduler -> etcd [ label=" Set Host of VM in etcd [7]\nand Create Request to Start VM"]
}
```
### VM Start
```graphviz
digraph {
node [ shape="box"];
subgraph cluster_etcd {
etcd
}
etcd -> host [label=" Fetch VM Start Requests [8]"]
subgraph cluster_host {
host -> start_vm [label="[9]"]
start_vm
}
start_vm -> etcd [label=" Set VM Status to Running"]
start_vm -> ceph_cluster [label=" If VM isn't created already then Copy VM's base image\n to uservms pool and rename it to match VM's uuid [9a]"]
ceph_cluster -> start_vm [label="VM Created [9b]"]
start_vm -> ceph_cluster [label="Start VM [10]"]
subgraph cluster_ceph {
ceph_cluster [label="CEPH Cluster"]
}
}
```
### VM Migrate
**TBD: ahmed**
### VM Delete
**TBD: ahmed**
## Networking
**TBD: Nico**
Networks are always layer 2 entities. They might provide IPAM (IP address management) services and routing additionally. IPAM is always IPv6 router advertisements. VMs that support only IPv4 are not supported. All layer2 networks are implemented as VXLANs. VXLANs are implemented with IPv6 Multicasting.
### Network Types
| Network type | Description|
|-----|-----|
| Layer 2 without IPAM | No IPAM, no routing |
| Layer 2 with manual IPAM | User gets a /64 network assigned, but no RAs |
| Layer 2 with automatic IPAM | Users gets /64 assigned and RAs in the network |
### Network Create: all types
**TBD: nico**
* Need to distinguish layer2 vs. layer2 + ipam
```graphviz
digraph {
label="Create VM with ucloud"
cli->api->etcd->ucloudnetwork;
}
```
### Network Create: without IPAM
* Network is usable for user directly
* When VM is started, network might be created on host
* Status: 90% done,
```graphviz
digraph {
label="Create VM with ucloud"
cli;
createnetwork [ label="Create VXLAN on device, create bridge"]
createonhost [ label="Create VM on host"]
cli->api [ label="Start VM with network 'layer2only'" ];
api->etcd->scheduler;
ucloudhost->etcd [ label="checks for new vm"]
ucloudhost->ucloudhost [ label="Wait until network exists"]
ucloudnetwork->etcd [ label="Check for new networks"]
ucloudhost->createonhost [ label="Create VM in network(s)"]
ucloudnetwork->network [ label="Check whether network exists locally"]
network->createnetwork [ label="no"];
network->noop [ label="yes"]
subgraph cluster_anywhere {
api
etcd
}
subgraph cluster_host {
ucloudhost;
ucloudnetwork;
host;
network;
createnetwork;
createonhost;
noop;
}
}
```
### Network Create: manual and automatic IPAM
Extending the flow from the case for managing networks
```graphviz
digraph {
label="Create VM with ucloud"
newvxlan [ label="Assign new VXLAN ID"]
newnet [ label="Assign new /64 IPv6 network"]
needsnet [ label="Needs IPAM?"]
radvd [ label="Create RA instance (radvd)"]
etcd->ucloudnetworkmanager [ label="New network requests"]
ucloudnetworkmanager->newvxlan;
newvxlan->needsnet;
needsnet->newnet [ label="yes" ]
needsnet->done [ label="no" ]
newnet->done [ label="Manual IPAM"]
newnet->radvd [ label="Automatic IPAM"];
radvd->done;
done;
subgraph cluster_router {
label="Router";
radvd;
}
}
```
### Network configuration
How a VM learns / gets to know its IP addresses.
Every VM can have 0 or more network interfaces. Each network interface is connected to a network.
### Network routing
## From zero to fully functional ucloud cluster (non ceph, development)
**to be filled in by Ahmed**
### Requirements
* 1 machine
### Outcome
* ucloud running w/o VM migration
### Notes
We can use this case as a base for development. We might add VM migration (w/ copying files later)
## From zero to fully functional ucloud cluster (ceph, production)
```bash=
# We assume that the ceph configuration files are already in place
# i.e under /etc/ceph/
// Only needed on alpine linux
apk add git
git clone https://code.ungleich.ch/ungleich-public/ucloud-setup; cd ucloud-setup; sh ./init.sh
pipenv run python ucloud-setup.py api setup --auth_name ahmedbilal-auth --auth_realm ungleich-auth \
--auth_seed VVEDPGTP776FSZX4 --realm_allowed ungleich-admin --realm_allowed ungleich-user --path ../ --etcd_url [2a0a:e5c0:0:2:0:b3ff:fe39:7994]
pipenv run python ucloud-setup.py scheduler setup --vm_prefix /v1/vm --host_prefix /v1/host \
--request_prefix /v1/request --path ../ --etcd_url [2a0a:e5c0:0:2:0:b3ff:fe39:7994]
pipenv run python ucloud-setup.py host setup --path ../ --ssh_username abc \
--ssh_key_path ~/.ssh/id_rsa --ssh_key_pass meow --etcd_url [2a0a:e5c0:0:2:0:b3ff:fe39:7994]
pipenv run python ucloud-setup.py file-scan setup --path ../ --base_dir /var/www \
--file_prefix /v1/file --etcd_url [2a0a:e5c0:0:2:0:b3ff:fe39:7994]
pipenv run python ucloud-setup.py image setup --path ../ --base_dir /var/www --etcd_url [2a0a:e5c0:0:2:0:b3ff:fe39:7994]
(cd ~/ucloud-api && pipenv run python ~/ucloud-api/create_image_store.py)
```
## Optional services
Services that make sense in the cloud environment that can be added and managed by ucloud.
### Forward DNS setup
* Offer a variety of zones customers can pick from
* Limit to a certain amount of entries to prevent over use?
### Reverse DNS setup
**TBD: describe: nico**
* A user can configure the reverse DNS of every VM she controls
* We need a "sane" way to deal with delegated/routed networks
### Console access (ucloud-vnc-console)
**TBD: Jinguk: implement it**
**TBD: Ahmed** we need a service that sets up database entries in guacamole
* A user can access the console of a VM by VNC
* We use guacamole for this purpose
### IPv4 address
A user can request an IPv4 address for a VM.
### Billing
We need to have Mondi/Ahmed/Nico for this
* Adding a price tag on things
* Can be per minute
## User Guide
This guide describes how to use ucloud as a user.
### User Setup
**TBD: Ahmed**
* uotp token explained
* how to install cli
### How to create a VM
**TBD: Ahmed**
First time:
* upload file
* create image from it (?)
* create a layer2 network with IPAM
Afterwards:
* create vm
* all steps in detail