Skip to content
Snippets Groups Projects

Compare revisions

Changes are shown as if the source revision was being merged into the target revision. Learn more about comparing revisions.

Source

Select target project
No results found
Select Git revision
  • identities
  • master
  • windows-in-cloud
3 results

Target

Select target project
  • cloud/documentation
  • 242618/documentation
  • 469240/documentation
  • LukasD/documentation
  • 35475/documentation
  • 323969/documentation
6 results
Select Git revision
  • feature/S3_section
  • feature/add_loadbalance_info
  • feature/adding_img_vision_details
  • feature/commu_image
  • feature/cosmetic_fixes
  • feature/ipv6-metadata
  • feature/news_add
  • feature/old-docs-redir
  • fix_menu_title_part2
  • freznicek-table-row-provisioning
  • identities
  • image-rot-logs/2022-01-17
  • image-rot-news-section
  • image-rotation-publish
  • img_rot_gen_fix
  • master
  • new_docs
  • new_os_projects_req_page
  • news_add1
  • old_documentation
  • revert-9daae260
  • small-change-pipeline
  • test/ci
  • test/deploy1
  • upgrade/theme-version
25 results
Show changes
Commits on Source (99)
# Compiled book
/_book/
# Build deps
/node_modules/
# requiring the environment of NodeJS 10
image: node:10
# add 'node_modules' to cache for speeding up builds
cache:
paths:
- node_modules/ # Node modules and dependencies
before_script:
- apt-get update && apt-get -y install calibre # needed for conversion to PDF
- npm install gitbook-cli -g # install gitbook
- gitbook fetch 3.2.3 # fetch final stable version
- gitbook install # add any requested plugins in book.json
# the 'pages' job will deploy and build your site to the 'public' path
pages:
stage: deploy
script:
- gitbook build . public # build to public path
- gitbook pdf . public/mcc-user-guide.pdf # add PDF version
artifacts:
paths:
- public
expire_in: 1 week
only:
- master # this job will affect only the 'master' branch
## Virtual Machine Instance
Server-like resource in OpenStack
## Security Group
Firewall-like resource in OpenStack
## Project
Resource ownership unit in OpenStack
## Floating IP Address
Public/external IP resource in OpenStack
## Image
Operating system resource in OpenStack
## Volume
Storage allocation resource in OpenStack
## SSH
Secure Shell
## SSH Key Pair
Set of keys for asymmetric cryptography, used for secure remote access
## User Support
[cloud@metacentrum.cz](mailto:cloud@metacentrum.cz)
## MUNI Identity Management
[idm@ics.muni.cz](mailto:idm@ics.muni.cz)
## VO
Virtual Organization, unit of organizational hierarchy
# Introduction
<div style="border-width:0;border-left:5px solid #b8d6f4;background-color:rgba(255,0,0,0.3);margin:20px 0;padding:10px 20px;font-size:15px;">
<strong>WARNING:</strong><br/><br/>
Please read the new section in order to choose a proper networks for your needs.
</div>
[click here](/important/README.md)
This guide aims to provide a walk-through for setting up a rudimentary
virtual infrastructure in MetaCentrum Cloud. It is a good jumping-off
point for most users.
The left sidebar can be used for navigation throughout the documentation.
The whole guide can also be downloaded as PDFs for printing or later use.
__New users__ should head over to the [Get Access](/register/README.md)
section and make sure they have an active user account and required
permissions to access the service.
__Beginners__ should start in the [Quick Start](/quick-start/README.md)
section which provides a step-by-step guide for starting the first
virtual machine instance.
__Advanced users__ should continue in the [Advanced Features](/gui/README.md)
or [Command Line Interface](/cli/README.md) sections, as these are
more suitable for complex use cases and exploration of available
features.
__Expert users__ with complex infrastructural or scientific use cases
should contact user support and request assistance specifically for
their use case.
__Frequently asked questions__ and corresponding answers can be found in
the [FAQ](/faq/README.md) section. Please, consult this section before
contacting user support.
Bear in mind that this is not the complete documentation to OpenStack
but rather a quick guide that is supposed to help you with elementary
use of our infrastructure. If you need more information, please turn
to [the official documentation](https://docs.openstack.org/rocky/user/)
or contact user support and describe your use case.
Please visit [Network](/network/README.md) section in order to see how you should set up the network.
* [IMPORTANT](/important/README.md)
* [Introduction](/README.md)
* [Get Access](/register/README.md)
* [Migrate](/migrate/README.md)
* [Quick Start](/quick-start/README.md)
* [Advanced Features](/gui/README.md)
* [Command Line Interface](/cli/README.md)
* [Openstack Networking](/network/README.md)
* [FAQ](/faq/README.md)
* [Contribute](/contribute/README.md)
{
"title": "MetaCentrum Cloud - User Guide",
"description": "This guide aims to provide basic user manual for the user of MetaCentrum Cloud.",
"author": "The MetaCentrum Cloud Team <cloud@metacentrum.cz>",
"language": "en",
"plugins": [
"get-book",
"hints-istex",
"page-toc"
],
"pluginsConfig": {
"get-book": {
"url": "https://cloud.gitlab-pages.ics.muni.cz/documentation/mcc-user-guide.pdf",
"label": "Download as PDF"
},
"hints": {
"info": "fa fa-info-circle",
"success": "fa fa-check-circle",
"danger": "fa fa-exclamation-triangle",
"warning": "fa fa-exclamation-circle"
},
"page-toc": {
"selector": ".markdown-section h2, .markdown-section h3, .markdown-section h4",
"position": "top",
"showByDefault": true
}
}
}
# Command Line Interface
In order to have access to OpenStack's API, you have to use so-called OpenStack Application Credentials. In short,
it is a form of token-based authentication providing easy and secure access without the use of passwords.
## Getting Credentials
1. In **Identity &gt; Application Credentials**, click on **Create Application Credential**.
2. Choose name, description and expiration date & time.
![](/cli/images/app_creds_1.png)
<div style="border-width:0;border-left:5px solid #b8d6f4;background-color:rgba(228,240,251,0.3);margin:20px 0;padding:10px 20px;font-size:15px;">
<strong>Notice:</strong><br/>
Do NOT select specific roles, unless directed otherwise by user support.
</div>
<div style="border-width:0;border-left:5px solid #b8d6f4;background-color:rgba(228,240,251,0.3);margin:20px 0;padding:10px 20px;font-size:15px;">
<strong>Notice:</strong><br/>
If you decide to select specific roles, you should always include at least the <strong>member</strong> role.
If you are planning to use the orchestration API, add the <strong>heat_stack_owner</strong> role as well and
check <strong>Unrestricted</strong>.
</div>
3. Download provided configuration files for the OpenStack CLI client.
![](/cli/images/app_creds_2.png)
## Setting Up
1. [Install](https://pypi.org/project/python-openstackclient/) and
[configure](https://docs.openstack.org/python-openstackclient/rocky/configuration/index.html)
OpenStack CLI client.
<div style="border-width:0;border-left:5px solid #b8d6f4;background-color:rgba(255,0,0,0.3);margin:20px 0;padding:10px 20px;font-size:15px;">
<strong>WARNING:</strong><br/><br/>
Add the following line to the <strong>openrc</strong> file:<br/>
<strong>export OS_VOLUME_API_VERSION=3</strong>
<br/><br/>
Add the following line to the <strong>clouds.yaml</strong> file:<br/>
<strong>volume_api_version: 3</strong>
</div>
2. Follow the official [Launch instances](https://docs.openstack.org/nova/rocky/user/launch-instances.html) guide.
---
## Creating a key-pair
1. Assuming your ssh public key is stored in `~/.ssh/id_rsa.pub`
```
openstack keypair create --public-key ~/.ssh/id_rsa.pub my-key1
```
## Create security group
1. Create:
```
openstack security group create my-security-group
```
2. Add rules to your security group:
```
openstack security group rule create --description "Permit SSH" --remote-ip 0.0.0.0/0 --protocol tcp --dst-port 22 --ingress my-security-group
openstack security group rule create --description "Permit ICMP (any)" --remote-ip 0.0.0.0/0 --protocol icmp --icmp-type -1 --ingress my-security-group
```
3. Verify:
```
openstack security group show my-security-group
```
## Create network
1. Create network + subnet (from auto-allocated pool)
```
openstack network create my-net1
openstack subnet create --network my-net1 --subnet-pool private-192-168 my-sub1
```
2. Create router:
```
openstack router create my-router1
```
Current router have no ports, which makes it pretty useless, we need to create at least 2 interfaces (external and internal)
3. Set external network for router (let us say public-muni-147-251-124), and the external port will be created automatically:
```
openstack router set --external-gateway public-muni-147-251-124 my-router1
```
4. Check which IP address is set as gateway for our subnet (default: first address of the subnet):
```
GW_IP=$(openstack subnet show my-sub1 -c gateway_ip -f value)
```
5. Create internal port for router (gateway for the network my-net1):
```
openstack port create --network my-net1 --disable-port-security --fixed-ip ip-address=$GW_IP my-net1-port1-gw
```
6. Add port to the router:
```
openstack router add port my-router1 my-net1-port1-gw
```
## Create volume
<div style="border-width:0;border-left:5px solid #b8d6f4;background-color:rgba(228,240,251,0.3);margin:20px 0;padding:10px 20px;font-size:15px;">
<strong>WARNING:</strong><br/>
Skipping this section can lead to unreversible loss of data
</div>
Volumes are create automatically when creating an instance in GUI, but we need to create them manually in case of CLI
1. Create bootable volume from image(e.g. centos):
```
openstack volume create --image "centos-7-1809-x86_64" --size 40 my_vol1
```
## Create server
1. Create instance:
```
openstack server create --flavor "standard.small" --volume my_vol1 \
--key-name my-key1 --security-group my-security-group --network my-net1 my-server1
```
## Assign floating ip address
1. Create and assign floating IP address:
```
FLOAT_IP=$(openstack floating ip create --description my-float1 -c floating_ip_address -f value public-muni-147-251-124)
openstack server add floating ip my-server1 $FLOAT_IP
```
## Full Reference
See [OpenStack CLI Documentation](https://docs.openstack.org/python-openstackclient/rocky/).
cli/images/app_creds_1.png

109 KiB

cli/images/app_creds_2.png

60.1 KiB

# How To Contribute
## Requirements
Working with our documentation requires the following tools:
* *git* for version control
* *nodejs* and *gitbook* for content management
This documentation is written in the *Markdown* markup language.
```bash
# Debian
apt-get install nodejs git
```
```bash
# CentOS
yum install nodejs git
```
```bash
# Fedora
dnf install nodejs git
```
Or see [NodeJS Documentation](https://nodejs.org/en/download/package-manager/) for distro-specific instructions.
## Work-flow Overview
1. Fork & clone repository
2. Create a branch
3. Commit your changes
4. Push to the branch
5. Create a Merge Request with the content of your branch
## Fork Repository
See [GitLab @ ICS MU](https://gitlab.ics.muni.cz/cloud/documentation/forks/new) for details. This will create your own clone of our repository where you will be able to make changes. Once you are happy with your changes, use GitLab to submit them to our original repository.
## Clone Repository
```bash
# after creating your own copy of the repository on GitLab
git clone git@gitlab.ics.muni.cz:${GITLAB_USER}/documentation.git
```
## Create New Branch
```bash
# in `documentation`
git checkout -b my_change
```
## Install GitBook
```bash
npm install gitbook-cli -g
# in `documentation`
gitbook install
```
This step MAY require `sudo` depending on your system and NodeJS installation method.
## Edit GitBook
```bash
# in `documentation`
gitbook serve
```
> Edits will be show live in your browser window, no need to refresh.
## Commit and Push Changes
```bash
git commit -am "My updates"
git push origin my_change
```
## Submit Changes
Create a *Merge Request* via [GitLab @ ICS MU](https://gitlab.ics.muni.cz/cloud/documentation/merge_requests/new).
# Frequently Asked Questions
## How do I register?
Follow instructions for registering in [MetaCentrum Cloud](/register/README.md).
## How do I migrate from legacy platforms?
Follow instructions for [migrating from CESNET-MetaCloud or OStack ICS MUNI](/migrate/README.md).
## Where do I report a problem?
First, try searching the documentation for an answer to your problem. If that does not yield results, open a
ticket with [cloud@metacentrum.cz](mailto:cloud@metacentrum.cz). When contacting user support, always
include your *username* (upper right corner of the web interface) and *domain* with
active *project* (upper left corner of the web interface) as well as a description of
your problem and/or an error message if available.
## What networks I can use to access my instances?
Personal projects can allocate floating IPs from *public-muni-147-251-124* and *private-muni-10-16-116*.
Group projects can currently allocate floating IPs from *public-cesnet-78-128-251* and *private-muni-10-16-116*.
IP addresses from *public-muni-147-251-124* allocated by users to group projects are released daily, so we encourage
using only *public-cesnet-78-128-251* and *private-muni-10-16-116* for group projects.
Follow instructions at [changing the external network](/network/README.md) in order to change your public network.
## Issues with network stability in Docker
OpenStack instances use 1442 bytes MTU (maximum transmission unit) instead of standard 1500 bytes MTU. Instance itself is
able to setup correct MTU with its counterpart via Path MTU Discovery. Docker needs MTU setup explicitly. Refer documentation for setting up
1442 MTU in [Docker](https://docs.docker.com/v17.09/engine/userguide/networking/default_network/custom-docker0/) or
[Kubernetes](https://docs.projectcalico.org/v3.5/usage/configuration/mtu).
## How many floating IPs does my group project need?
One floating IP per project should generally suffice. All OpenStack instances are deployed on top of internal OpenStack networks. These internal networks are not by default accessible from outside of OpenStack, but instances on top of same internal network can communicate with each other.
To access internet from an instance, or access instance from the internet, you could allocate floating public IP per instance. Since there are not many public IP addresses available and assigning public IP to every instance is not security best practise, both in public and private clouds these two concepts are used:
* **internet access is provided by virtual router** - all new OpenStack projects are created with *group-project-network* internal network connected to virtual router with public IP as a gateway. Every instance created with *group-project-network* can access internet through NAT provided by it's router by default.
* **accessing the instances:**
* **I need to access instances by myself** - best practice for accessing your instances is creating one server with floating IP called [jump host](https://en.wikipedia.org/wiki/Jump_server) and then access all other instances through this host. Simple setup:
1. Create instance with any Linux.
2. Associate floating IP with this instance.
3. Install [sshuttle](https://github.com/sshuttle/sshuttle) on your client.
4. `sshuttle -r root@jump_host_fip 192.168.0.1/24`. All your traffic to internal OpenStack network *192.168.0.1/24* is now tunneled through jump host.
* **I need to serve content (e.g. webservice) to other users** - public and private clouds provide LBaaS (Load-Balancer-as-a-Service) service, which proxies users traffic to instances. We are planning to deploy this functionality in 2020. Currently you can create LB manually by installing and configuring e.g. HAproxy on your jump host.
In case, that these options are not suitable for you usecase, you can still request multiple floating IPs.
# Advanced Features
The following guide will introduce you to advanced features available in MetaCentrum Cloud.
For basic instructions on how to start a virtual machine instance, see [Quick Start](/quick-start/README.md).
## Virtual Networks
MetaCentrum Cloud offers software-defined networking as one of its services. Users have the ability to create their own
networks and subnets, connect them with routers, and set up tiered network topologies.
Prerequisites:
* Basic understanding of routing
* Basic understanding of TCP/IP
For details, refer to [the official documentation](https://docs.openstack.org/horizon/rocky/user/create-networks.html).
### Create Network
1. Go to **Project &gt; Network &gt; Networks**, click on **Create Network**.
2. Choose name and click **Next**.
3. In the subnet tab, choose a subnet name. In **Network Address Source**, select **Allocate Network Addres from a pool**.
In **Address pool** select any of the available pools. Click **Next**.
4. Click **Create**. Do not change any other options.
5. Go to **Project &gt; Network &gt; Network Topology**, review your newly created network topology.
![](/gui/images/network5.png)
### Create Router
1. Go to **Project &gt; Network &gt; Routers**, click on the **Create Router** button.
2. Choose a name. Select **External Network** and click **Create Router**.
<div style="border-width:0;border-left:5px solid #b8d6f4;background-color:rgba(228,240,251,0.3);margin:20px 0;padding:10px 20px;font-size:15px;">
<strong>Notice:</strong><br/>
Please, remember that your will have to allocate floating IP addresses in the selected External Network for all instances
using this router as a gateway.
</div>
3. Go to **Project &gt; Network &gt; Network Topology**, the newly create router should be now present.
![](/gui/images/router3.png)
4. Click on the router icon, select **Add Interface**.
![](/gui/images/router4.png)
5. Choose the previously created network/subnet from the drop-down menu. Click **Submit**.
![](/gui/images/router5.png)
6. The router is now attached to an external network.
![](/gui/images/router6.png)
<div style="border-width:0;border-left:5px solid #b8d6f4;background-color:rgba(228,240,251,0.3);margin:20px 0;padding:10px 20px;font-size:15px;">
<strong>Notice:</strong><br/>
Routers can also be used to route traffic between internal networks. This is an advanced topic not covered in this guide.
</div>
## Orchestration
The OpenStack orchestration service can be used to deploy and manage complex virtual topologies as single entities,
including basic auto-scaling and self-healing.
For details, refer to [the official documentation](https://docs.openstack.org/heat-dashboard/rocky/user/index.html).
## Image upload
We don't support uploading own images by default. MetaCentrum Cloud images are optimized for running in the cloud and we recommend users
to customize them instead of building own images from scratch. If you need upload custom image, please contact user support for appropriate permissions.
Instructions for uploading custom image:
1. Upload only images in RAW format (not qcow2, vmdk, etc.).
2. Upload is supported only through OpenStack [CLI](https://cloud.gitlab-pages.ics.muni.cz/documentation/cli/) with Application Credentials.
3. Each image needs to contain metadata:
```
hw_scsi_model=virtio-scsi
hw_disk_bus=scsi
hw_rng_model=virtio
hw_qemu_guest_agent=yes
os_require_quiesce=yes
```
Following needs to be setup correctly (consult official [documentation](https://docs.openstack.org/glance/rocky/admin/useful-image-properties.html#image-property-keys-and-values))
or instances won't start:
```
os_type=linux # example
os_distro=ubuntu # example
```
4. Images should contain cloud-init, qemu-guest-agent and grow-part tools
5. OpenStack will resize instance after start. Image shouldn't contain any empty partitions or free space
## Add SWAP file to instance
By default VMs after creation do not have SWAP partition. If you need to add a SWAP file to your system you can download and run [script](https://gitlab.ics.muni.cz/cloud/cloud-tools/blob/master/swap.sh) that create SWAP file on your VM.
gui/images/network1.png

38.6 KiB

gui/images/network2.png

28.7 KiB

gui/images/network3.png

42.5 KiB

gui/images/network4.png

26.9 KiB

gui/images/network5.png

18 KiB

gui/images/router1.png

26.1 KiB

gui/images/router2.png

20.9 KiB

gui/images/router3.png

18.6 KiB