ionoscloud

README

Introduction

This library adds the support for creating Docker Machines hosted on IONOS Cloud.

Overview

Docker Machine Driver is the official driver for Docker Machine to use with IONOS Cloud. It adds support for creating Docker Machines hosted on the IONOS Cloud.

Docker Machine lets you create Docker hosts on your computer and inside your own data center. It creates servers, installs Docker on them, then configures the Docker client to talk to them. For more information about Docker Machine, check the official GitHub Repository.

---

Warning: API Basic Authentication Deprecation Notice

Effective March 15, 2024, IONOS account holders using 2-Factor Authentication will no longer be able to utilize Basic Authentication for accessing our APIs, SDKs, and all related tools. Token creation and deletion via APIs and ionosCTL will also be restricted.

Affected users are required to switch to token-based authorization. These tokens will be accessible through our new Token Manager in the Data Center Designer, launching at the beginning of February 2024. More information can be found here.

---

Getting started

Setup

Option 1: Use with Rancher docker image

• Run the Rancher docker image on a publicly accessible server, reachable on ports 80 and 443: docker run -d --name=rancher-server --restart=unless-stopped -p 80:80 -p 443:443 --privileged rancher/rancher:v2.6.8
• Add the Node Driver. Usage of the UI driver is highly recommended, but not necessary: [server-ip]/dashboard/c/local/manager/pages/rke-drivers

    * Download URL: https://github.com/ionos-cloud/docker-machine-driver/releases/download/v<version>/docker-machine-driver-<version>-linux-amd64.tar.gz
    * Custom UI URL:  https://cdn.jsdelivr.net/gh/ionos-cloud/ui-driver-ionoscloud@main/releases/v<UI_version|latest>/component.js  
    * Whitelist Domains: cdn.jsdelivr.net

• The Docker Machine Driver for Ionoscloud is ready to use. Refer to the Rancher Cluster section for version-specific instructions and further help with creating RKE1 templates and provisioning clusters.

Option 2: Use with docker-machine or rancher-machine CLIs

Check the Release Page and find the corresponding archive for your operating system and architecture. You can download the archive from your browser or you can follow the next steps:

# Check if /usr/local/bin is part of your PATH
echo $PATH

# Download and extract the binary (<version> is the full semantic version): 
curl -sL https://github.com/ionos-cloud/docker-machine-driver/releases/download/v<version>/docker-machine-driver-<version>-linux-amd64.tar.gz | tar -xzv

# Move the binary somewhere in your $PATH:
sudo mv ~/docker-machine-driver-ionoscloud /usr/local/bin

# See options for the driver to use with the Docker Machine CLI
docker-machine create --help --driver ionoscloud

# See options for the driver to use with the Rancher Machine CLI
rancher-machine create --help --driver ionoscloud

For Windows users, you can download the latest release available on Release Page, unzip it and copy the binary in your PATH. You can follow this official guide that explains how to add tools to your PATH.

Building From Source

Prerequisites

Please refer to the Go Install Documentation if you do not have Go installed and configured for your system.

Run the following commands to install the Ionos Cloud Docker Machine Driver:

git clone https://github.com/ionos-cloud/docker-machine-driver.git

After cloning the repository, you can build and install the driver itself:

cd $DIRECTORY_PATH/docker-machine-driver
make install

When successful, we will end up with a newly created docker-machine-driver-ionoscloud binary in docker-machine-driver/bin/ and in $GOPATH/bin/.

Depending on how your $PATH is being set, you may need to copy the binary to $PATH in order to use the Docker Machine Driver.

sudo cp $DIRECTORY_PATH/docker-machine-driver/bin/docker-machine-driver-ionoscloud /usr/local/bin/docker-machine-driver-ionoscloud

Note that the development version is a work-in-progress of a future stable release and can include bugs. Officially released versions will generally be more stable. Check the latest releases in the Release Page.

Usage

Before you start using the Ionos Cloud Docker Machine Driver, you need to authenticate in your Ionos Cloud account. Check the steps in the Authentication section.

In order to see the available options and flags, check the Options section.

For more information about Docker/Rancher Machine commands on how to manage a machine, including examples, check the Commands section.

Docker Support

For information on how to create a Docker Machine with Ionos Cloud Docker Machine Driver, check the Docker Machine section.

For information on how to create a Docker Machine with Ionos Cloud Docker Machine Driver with Swarm Mode, check the Docker Swarm section.

For more details about possible issues, check the Troubleshooting section.

Rancher Support

For information on how to create a Rancher Machine with Ionos Cloud Docker Machine Driver, check the Rancher Machine section.

For information on how to create a Rancher Cluster via Rancher UI, using Ionos Cloud Docker Machine Driver, check the Rancher Cluster section.

Feature Reference

The IONOS Cloud Docker Machine Driver aims to offer access to all resources in the IONOS Cloud API and also offers some additional features that make the integration easier:

• authentication for API calls
• handling of asynchronous requests

Contributing

Bugs & feature requests can be open on the repository issues: https://github.com/ionos-cloud/docker-machine-driver/issues/new/choose

Can I contribute to the Docker Machine Driver?

Sure! Our repository is public, feel free to fork it and file a PR for one of the issues opened in the issues list. We will review it and work together to get it released.

License

Apache 2.0

Documentation

Index

• Variables
• func NewDriver(hostName, storePath string) drivers.Driver
• type Driver
  • func NewDerivedDriver(hostName, storePath string) *Driver
  • func (d *Driver) Create() (err error)
  • func (d *Driver) CreateDataCenterIfNeeded() (err error)
  • func (d *Driver) CreateIonosMachine() (err error)
  • func (d *Driver) CreateIonosNatAndSetIp() (err error)
  • func (d *Driver) CreateIonosServer() (err error)
  • func (d *Driver) CreateLanIfNeeded() (err error)
  • func (d *Driver) DriverName() string
  • func (d *Driver) GetCreateFlags() []mcnflag.Flag
  • func (d *Driver) GetFinalUserData() (userdata string, err error)
  • func (d *Driver) GetIP() (string, error)
  • func (d *Driver) GetSSHHostname() (string, error)
  • func (d *Driver) GetSSHUsername() string
  • func (d *Driver) GetState() (state.State, error)
  • func (d *Driver) GetURL() (string, error)
  • func (d *Driver) Kill() error
  • func (d *Driver) PreCreateCheck() error
  • func (d *Driver) Remove() error
  • func (d *Driver) Restart() error
  • func (d *Driver) SetConfigFromFlags(opts drivers.DriverOptions) error
  • func (d *Driver) Start() error
  • func (d *Driver) Stop() error

Variables

var DriverVersion string

DriverVersion will be set at every new release For working locally with the Docker-Machine-Driver, it will be set to `DEV`.

Functions

func NewDriver

func NewDriver(hostName, storePath string) drivers.Driver

NewDriver returns a new driver instance.

Types

type Driver

type Driver struct {
	*drivers.BaseDriver

	URL      string
	Username string
	Password string
	Token    string

	Ram                    int
	Cores                  int
	SSHKey                 string
	SSHUser                string
	DiskSize               int
	DiskType               string
	Image                  string
	ImagePassword          string
	Size                   int
	NicDhcp                bool
	NicIps                 []string
	ReservedIps            *[]string
	Location               string
	CpuFamily              string
	ServerType             string
	Template               string
	DCExists               bool
	LanExists              bool
	NatExists              bool
	UseAlias               bool
	VolumeAvailabilityZone string
	ServerAvailabilityZone string
	LanId                  string
	LanName                string
	AdditionalLans         []string
	AdditionalLansIds      []int
	AdditionalNicsIds      []string
	DatacenterId           string
	DatacenterName         string
	VolumeId               string
	NicId                  string
	ServerId               string
	IpBlockId              string
	CreateNat              bool
	NatName                string
	NatId                  string
	CloudInit              string
	CloudInitB64           string
	NatPublicIps           []string
	NatFlowlogs            []string
	NatRules               []string
	SkipDefaultNatRules    bool
	NatLansToGateways      map[string][]string
	PrivateLan             bool
	IsLanPrivate           bool
	SSHInCloudInit         bool
	WaitForIpChange        bool
	WaitForIpChangeTimeout int

	// Driver Version
	Version string
	// contains filtered or unexported fields
}

func NewDerivedDriver

func NewDerivedDriver(hostName, storePath string) *Driver

func (*Driver) Create

func (d *Driver) Create() (err error)

Create creates the machine.

func (*Driver) CreateDataCenterIfNeeded

func (d *Driver) CreateDataCenterIfNeeded() (err error)

func (*Driver) CreateIonosMachine

func (d *Driver) CreateIonosMachine() (err error)

func (*Driver) CreateIonosNatAndSetIp

func (d *Driver) CreateIonosNatAndSetIp() (err error)

func (*Driver) CreateIonosServer

func (d *Driver) CreateIonosServer() (err error)

func (*Driver) CreateLanIfNeeded

func (d *Driver) CreateLanIfNeeded() (err error)

func (*Driver) DriverName

func (d *Driver) DriverName() string

DriverName returns the name of the driver

func (*Driver) GetCreateFlags

func (d *Driver) GetCreateFlags() []mcnflag.Flag

GetCreateFlags returns list of create flags driver accepts.

func (*Driver) GetFinalUserData

func (d *Driver) GetFinalUserData() (userdata string, err error)

func (*Driver) GetIP

func (d *Driver) GetIP() (string, error)

GetIP returns public IP address or hostname of the machine instance.

func (*Driver) GetSSHHostname

func (d *Driver) GetSSHHostname() (string, error)

GetSSHHostname returns an IP address or hostname for the machine instance.

func (*Driver) GetSSHUsername

func (d *Driver) GetSSHUsername() string

func (*Driver) GetState

func (d *Driver) GetState() (state.State, error)

GetState returns the state of the machine role instance.

func (*Driver) GetURL

func (d *Driver) GetURL() (string, error)

GetURL returns a socket address to connect to Docker engine of the machine instance.

func (*Driver) Kill

func (d *Driver) Kill() error

Kill stops the machine instance

func (*Driver) PreCreateCheck

func (d *Driver) PreCreateCheck() error

PreCreateCheck validates if driver values are valid to create the machine.

func (*Driver) Remove

func (d *Driver) Remove() error

Remove deletes the machine and resources associated to it.

func (*Driver) Restart

func (d *Driver) Restart() error

Restart reboots the machine instance.

func (*Driver) SetConfigFromFlags

func (d *Driver) SetConfigFromFlags(opts drivers.DriverOptions) error

SetConfigFromFlags initializes driver values from the command line values.

func (*Driver) Start

func (d *Driver) Start() error

Start issues a power on for the machine instance.

func (*Driver) Stop

func (d *Driver) Stop() error

Stop issues a power off for the machine instance.