Getting Started¶
Requirements¶
VCenter 6.5¶
You must have a ready to use VCenter server with the following resources:
- At least one Datastore
- At least one VM Compute Cluster
- At least one Host
- At least one non-management Port Group
The firewall on all hosts (within a cluster) that will be added to Sandwich Cloud needs to allow outgoing connections on the “VM serial port connected to vSPC” service.
All hosts MUST be able to connect to your workstation on port 13370. This is used for the Sandwich Cloud Metadata Service. Without this instances will not be able to get networking configuration.
Networking¶
The mentioned Port Group in the VCenter requirements must be connected to a layer 3 network that is reachable from your workstation. It is recommended that no other devices be on this network aside from a router to prevent possible IP address overlaps.
Workstation¶
- Internet Access
- Docker
- If you are not using Docker for Mac or Docker for Windows the steps in “Setting up the CLI” may need to be modified to fit your environment.
Setting up the Environment¶
For this guide we will be using the Sandwich Cloud quick-start repository that will spin up Sandwich Cloud containers and it’s dependencies using docker-compose.
So let’s start by cloning the repository and changing our working directory to it.
git clone https://github.com/sandwichcloud/quick-start.git
cd quick-start
Configuration¶
Most of the configuration items are already set however we still need to configure a few things.
First copy the .env-sample
file to .env
cp .env-sample .env
Under the VCENTER
heading enter your connection parameters used to
onnect to your VCenter server. It is recommended to use a user that has admin
privileges, however any user with the correct permissions will work.
VCENTER_HOST=vcenter.exmple.com
VCENTER_PORT=443
VCENTER_USERNAME=administrator@vsphere.local
VCENTER_PASSWORD=password123
You also must give the MENU_URL
. This is the telnet url to the metadata
service for Sandwich Cloud. The host in this url should be your workstation’s
address and must be reachable by your compute hosts. The metadata service’s port
is set to 13370 and must be given in the url.
MENU_URL=telnet://192.168.0.32:13370
Launching¶
Now that everything is configured we can go ahead and launch all the services.
docker-compose up
You must wait until all services are started before continuing. You will see the following output when everything is done launching:
deli-manager_1 | [2018-01-11T01:20:58+0000][deli.manager.cli.commands.run.RunManager][INFO] Creating CRDs
deli-menu_1 | [2018-01-11T01:20:58+0000][deli.menu.vspc.server.VSPCServer][INFO] Serving on ('0.0.0.0', 13370)
deli-manager_1 | [2018-01-11T01:21:08+0000][deli.manager.cli.commands.run.RunManager][INFO] CRDs have been created
Create the database¶
The quick-start is configured to use Database Auth so you must run the database migrations.
docker-compose exec deli-counter deli_counter database upgrade
Creating the admin user¶
The admin user is not created by default so we must create it and generate a password.
You can do that by running the following command:
docker-compose exec deli-counter deli_counter database gen-admin
Make a note of the password as it will be used later.
First Steps¶
Setting up the CLI¶
To get started you first need to download the CLI. Download the latest release of the CLI from https://github.com/sandwichcloud/deli-cli/releases.
Once the CLI is downloaded you need to configure it to connect to the api server:
export DLEI_API_SERVER=http://localhost:8080
Now you can login to the API:
deli auth login -u admin
When prompted enter the password for the generated admin user. Once verified an
API token will be generated and saved in ~/.sandwich/credentials
. This
API token will automatically be used by the CLI to authenticate against the API.
Creating a Region¶
In Sandwich Cloud, a Region is linked to a VCenter Datacenter as well as an Image Datastore.
The Image Datastore is just a VCenter Datastore that we designate as our Image storage. This Datastore must be connected to all VCenter Compute Clusters that you want to make available to Sandwich Cloud.
You can create a region by running the following:
deli region create --datacenter ${DATACENTER_NAME} --image-datastore ${DATASTORE_NAME} region1
Make a note of the region id as this will be used later.
Now that we have a region we need to enable scheduling to it. If we don’t VMs cannot be launched in this region.
deli region update --schedulable ${REGION_ID}
Creating a Network¶
Networks are unique to Regions and require a VCenter Port Group. This Port Group must be connected to all VCenter Compute Clusters that you want to make available.
You also must already have a routable address space available for that Port Group. It is recommended that there are no other devices other than a router present on this address space.
To get started please have handy the CIDR and the default gateway for the address space. You also must decide on an address pool within the CIDR. This typically ranges from the first usable address to the last usable address, the gateway will be automatically excluded from this range.
We will be using Google’s DNS servers to make things simple, however feel free to substitute your own. At least one DNS server must be given.
Once you have those run the following command:
deli network create --port-group ${PORT_GROUP} --region-id ${REGION_ID} \
--cidr ${CIDR} --gateway ${GATEWAY} --dns-server 8.8.8.8 --dns-server 8.8.4.4 \
--pool-start ${POOL_START} --pool-end ${POOL_END} my-network
Make a note of the network id as this will be used later.
Creating a Zone¶
Zones, unique to Regions, are linked to VCenter Compute Clusters. They also, similar to regions, require their own Datastore that we call the VM Datastore. The VM Datastore must be shared across all Hosts within the VM Compute Cluster and will store all active VMs and Volumes within the Zone.
To create a zone run the following:
deli zone create --region-id ${REGION_ID} --vm-cluster ${VM_COMPUTE_CLUSTER} \
--vm-datastore ${VM_DATASTORE} region1-a
Creating a Project¶
Now that we have added compute resources we can logically separate these resources into Projects. Projects can be specific to applications, teams, or departments, it is really up to you.
deli project create my-project
Now that you have your project you must configure your CLI to be scoped to that Project.
deli auth scope ${PROJECT_ID}
Scoping to a project simply takes your auth token and generates a new one that has permissions to modify resources within the Project. However don’t worry, your original token is still available and can still be used to interact with non-project based resources as well as scoping to other Projects.
By default projects are not allowed to create any resources, you can fix this by modifying the quota for the project.
deli project quota modify --vcpu=12 --ram=8182 --disk=100
If you don’t care about quota you can set vcpu, ram, and disk to -1 and the project will be able to use unlimited resources. However, setting project quotas is recommended as it is a good way to limit resource usage in your Datacenter.
Importing an Image¶
Before we launch an instance we first must have an Image to launch from.
An Image is simply a VM Template with a preinstalled OS configured in a certain way to be compatible with Sandwich Cloud.
Official Images can be downloaded from https://github.com/sandwichcloud/images/releases. If you do not wish to download a pre-build image feel free to build one yourself by using the packer scripts in https://github.com/sandwichcloud/images.
Once the Image is downloaded, un-compress it, upload it into the Image Datastore and create a VM with the only hard drive set to the downloaded VMDK. The VM should have the following hardware:
- 1 CPU
- 512MB Memory
- 1 Hard Disk (set to the downloaded vmdk)
- 1 SCSI Controller (set to VMware Paravirtual)
- 1 Network adapter
Do not add any other hardware to the VM as it may create issues with operation.
Do not boot up the VM as it will introduce unwanted log files into the image. Make sure the image is placed inside the Datacenter and Image Datastore you specified when you created the region.
Once the image is imported to VCenter convert it to a template then you can import it to Sandwich Cloud.
deli image import --region-id ${REGION_ID} my-new-image $TEMPLATE_NAME
Make a note of the image id as this will be used later.
Note
To read more about images and learn how to create your own see: Images
Creating a Flavor¶
Flavors define instances types or sizing of instances. Flavors control the vcpus, ram, and root disk size of instances.
By default there are no flavors defined so you must create one.
deli flavor create --vcpus 2 --ram 2048 --disk 20 my-flavor
Make a note of the flavor id as this will be used later.
Creating a SSH Keypair¶
You are almost ready to launch an instance but we are missing one piece, an SSH
key. For this guide we will be generating a new SSH key, however feel free to use
the import
command to import your own.
deli keypair generate my-keypair
Make a note of the keypair id as this will be used later.
Launching an Instance¶
Now you can finally launch the instance!
deli instance create --region-id ${REGION_ID} --network-id ${NETWORK_ID} \
--flavor-id ${FLAVOR_ID} --image-id ${IMAGE_ID} --keypair-id ${KEYPAIR_ID} my-instance
The instance will now be launching in VCenter. You can get the state of the instance by running the following command:
deli instance inspect ${INSTANCE_ID}
Once the instance state has changed to ‘Created’ it has now booted. To get the IP
address of the instance inspect the instance and find the network_port_id
,
then inspect the network port to grab it’s IP address:
deli network port inspect ${NETWORK_PORT_ID}
Now you can SSH into the instance!
ssh cloud-user@${IP_ADDRESS} -i ~/.ssh/id_my-keypair