Host

Hosts are the most basic unit of resource within Rancher and is represented as any Linux server, virtual or physical, with the following minimum requirements.

* Any modern Linux distribution with a supported version of Docker.
* Must be able to communicate with the Rancher server via http or https through the pre-configured port (Default is 8080).
* Must be routable to any other hosts belonging to the same environment to leverage Rancher’s cross-host networking for Docker containers.

Rancher also supports Docker Machine and allows you to add your host via any of its supported drivers.

Resource Fields

Writeable Fields

Field Type Create Update Default Notes
amazonec2Config amazonec2Config Optional Yes -  
authCertificateAuthority string Optional Yes -  
authKey string Optional Yes -  
azureConfig azureConfig Optional Yes -  
description string Optional Yes -  
digitaloceanConfig digitaloceanConfig Optional Yes -  
dockerVersion string Optional Yes -  
engineEnv map[string] Optional Yes -  
engineInsecureRegistry array[string] Optional Yes -  
engineInstallUrl string Optional Yes -  
engineLabel map[string] Optional Yes -  
engineOpt map[string] Optional Yes -  
engineRegistryMirror array[string] Optional Yes -  
engineStorageDriver string Optional Yes -  
hostname string Yes - -  
labels map[string] Optional Yes - A map of key value pairs to be used as labels for the host
localStorageMb int Optional Yes -  
memory int Optional Yes -  
milliCpu int Optional Yes -  
name string Optional Yes -  
packetConfig packetConfig Optional Yes -  
stackId stack Optional - -  

Read Only Fields

Field Type Notes
agentIpAddress string  
agentState string  
computeTotal int  
driver string  
id int The unique identifier for the host
info json  
instanceIds array[instance]  
physicalHostId physicalHost  
publicEndpoints array[publicEndpoint]  


Please read more about the common resource fields. These fields are read only and applicable to almost every resource. We have segregated them from the list above.

Operations

CreatePOST: /v2-beta/projects/${PROJECT_ID}/hosts

curl -u "${RANCHER_ACCESS_KEY}:${RANCHER_SECRET_KEY}" \
-X POST \
-H 'Content-Type: application/json' \
-d '{
	"amazonec2Config": {
		"accessKey": "",
		"ami": "",
		"blockDurationMinutes": "0",
		"deviceName": "/dev/sda1",
		"endpoint": "",
		"iamInstanceProfile": "",
		"insecureTransport": false,
		"instanceType": "t2.micro",
		"keypairName": "",
		"monitoring": false,
		"openPort": [
			"string1",
			"...stringN"
		],
		"privateAddressOnly": false,
		"region": "us-east-1",
		"requestSpotInstance": false,
		"retries": "5",
		"rootSize": "16",
		"secretKey": "",
		"securityGroup": [
			"docker-machine"
		],
		"sessionToken": "",
		"spotPrice": "0.50",
		"sshKeypath": "",
		"sshUser": "ubuntu",
		"subnetId": "",
		"tags": "",
		"useEbsOptimizedInstance": false,
		"usePrivateAddress": false,
		"userdata": "",
		"volumeType": "gp2",
		"vpcId": "",
		"zone": "a"
	},
	"authCertificateAuthority": "string",
	"authKey": "string",
	"azureConfig": {
		"availabilitySet": "docker-machine",
		"clientId": "",
		"clientSecret": "",
		"customData": "",
		"dns": "",
		"dockerPort": "2376",
		"environment": "AzurePublicCloud",
		"image": "canonical:UbuntuServer:16.04.0-LTS:latest",
		"location": "westus",
		"noPublicIp": false,
		"openPort": [
			"string1",
			"...stringN"
		],
		"privateIpAddress": "",
		"resourceGroup": "docker-machine",
		"size": "Standard_A2",
		"sshUser": "docker-user",
		"staticPublicIp": false,
		"storageType": "Standard_LRS",
		"subnet": "docker-machine",
		"subnetPrefix": "192.168.0.0/16",
		"subscriptionId": "",
		"usePrivateIp": false,
		"vnet": "docker-machine-vnet"
	},
	"description": "string",
	"digitaloceanConfig": {
		"accessToken": "",
		"backups": false,
		"image": "ubuntu-16-04-x64",
		"ipv6": false,
		"privateNetworking": false,
		"region": "nyc3",
		"size": "512mb",
		"sshKeyFingerprint": "",
		"sshKeyPath": "",
		"sshPort": "22",
		"sshUser": "root",
		"userdata": ""
	},
	"dockerVersion": "string",
	"engineEnv": {
		"key": "value-pairs"
	},
	"engineInsecureRegistry": [
		"string1",
		"...stringN"
	],
	"engineInstallUrl": "string",
	"engineLabel": {
		"key": "value-pairs"
	},
	"engineOpt": {
		"key": "value-pairs"
	},
	"engineRegistryMirror": [
		"string1",
		"...stringN"
	],
	"engineStorageDriver": "string",
	"hostname": "string",
	"labels": {
		"key": "value-pairs"
	},
	"localStorageMb": 0,
	"memory": 0,
	"milliCpu": 0,
	"name": "string",
	"packetConfig": {
		"apiKey": "",
		"billingCycle": "hourly",
		"facilityCode": "ewr1",
		"os": "ubuntu_14_04",
		"plan": "baremetal_1",
		"projectId": ""
	},
	"stackId": "reference[stack]"
}' 'http://${RANCHER_URL}:8080/v2-beta/projects/${PROJECT_ID}/hosts'

DeleteDELETE: /v2-beta/projects/${PROJECT_ID}/hosts/${ID}

curl -u "${RANCHER_ACCESS_KEY}:${RANCHER_SECRET_KEY}" \
-X DELETE \
'http://${RANCHER_URL}:8080/v2-beta/projects/${PROJECT_ID}/hosts/${ID}'

UpdatePUT: /v2-beta/projects/${PROJECT_ID}/hosts/${ID}

curl -u "${RANCHER_ACCESS_KEY}:${RANCHER_SECRET_KEY}" \
-X PUT \
-H 'Content-Type: application/json' \
-d '{
	"amazonec2Config": {
		"accessKey": "",
		"ami": "",
		"blockDurationMinutes": "0",
		"deviceName": "/dev/sda1",
		"endpoint": "",
		"iamInstanceProfile": "",
		"insecureTransport": false,
		"instanceType": "t2.micro",
		"keypairName": "",
		"monitoring": false,
		"openPort": [
			"string1",
			"...stringN"
		],
		"privateAddressOnly": false,
		"region": "us-east-1",
		"requestSpotInstance": false,
		"retries": "5",
		"rootSize": "16",
		"secretKey": "",
		"securityGroup": [
			"docker-machine"
		],
		"sessionToken": "",
		"spotPrice": "0.50",
		"sshKeypath": "",
		"sshUser": "ubuntu",
		"subnetId": "",
		"tags": "",
		"useEbsOptimizedInstance": false,
		"usePrivateAddress": false,
		"userdata": "",
		"volumeType": "gp2",
		"vpcId": "",
		"zone": "a"
	},
	"authCertificateAuthority": "string",
	"authKey": "string",
	"azureConfig": {
		"availabilitySet": "docker-machine",
		"clientId": "",
		"clientSecret": "",
		"customData": "",
		"dns": "",
		"dockerPort": "2376",
		"environment": "AzurePublicCloud",
		"image": "canonical:UbuntuServer:16.04.0-LTS:latest",
		"location": "westus",
		"noPublicIp": false,
		"openPort": [
			"string1",
			"...stringN"
		],
		"privateIpAddress": "",
		"resourceGroup": "docker-machine",
		"size": "Standard_A2",
		"sshUser": "docker-user",
		"staticPublicIp": false,
		"storageType": "Standard_LRS",
		"subnet": "docker-machine",
		"subnetPrefix": "192.168.0.0/16",
		"subscriptionId": "",
		"usePrivateIp": false,
		"vnet": "docker-machine-vnet"
	},
	"description": "string",
	"digitaloceanConfig": {
		"accessToken": "",
		"backups": false,
		"image": "ubuntu-16-04-x64",
		"ipv6": false,
		"privateNetworking": false,
		"region": "nyc3",
		"size": "512mb",
		"sshKeyFingerprint": "",
		"sshKeyPath": "",
		"sshPort": "22",
		"sshUser": "root",
		"userdata": ""
	},
	"dockerVersion": "string",
	"engineEnv": {
		"key": "value-pairs"
	},
	"engineInsecureRegistry": [
		"string1",
		"...stringN"
	],
	"engineInstallUrl": "string",
	"engineLabel": {
		"key": "value-pairs"
	},
	"engineOpt": {
		"key": "value-pairs"
	},
	"engineRegistryMirror": [
		"string1",
		"...stringN"
	],
	"engineStorageDriver": "string",
	"labels": {
		"key": "value-pairs"
	},
	"localStorageMb": 0,
	"memory": 0,
	"milliCpu": 0,
	"name": "string",
	"packetConfig": {
		"apiKey": "",
		"billingCycle": "hourly",
		"facilityCode": "ewr1",
		"os": "ubuntu_14_04",
		"plan": "baremetal_1",
		"projectId": ""
	}
}' 'http://${RANCHER_URL}:8080/v2-beta/projects/${PROJECT_ID}/hosts/${ID}'

Actions

activate POST: /v2-beta/projects/${PROJECT_ID}/hosts/${ID}?action=activate


Input:This action has no inputs


curl -u "${RANCHER_ACCESS_KEY}:${RANCHER_SECRET_KEY}" \
-X POST \
'http://${RANCHER_URL}:8080/v2-beta/projects/${PROJECT_ID}/hosts/${ID}?action=activate'


Output: An updated copy of the host resource

deactivate POST: /v2-beta/projects/${PROJECT_ID}/hosts/${ID}?action=deactivate


Input:This action has no inputs


curl -u "${RANCHER_ACCESS_KEY}:${RANCHER_SECRET_KEY}" \
-X POST \
'http://${RANCHER_URL}:8080/v2-beta/projects/${PROJECT_ID}/hosts/${ID}?action=deactivate'


Output: An updated copy of the host resource

dockersocket POST: /v2-beta/projects/${PROJECT_ID}/hosts/${ID}?action=dockersocket


Input:This action has no inputs


curl -u "${RANCHER_ACCESS_KEY}:${RANCHER_SECRET_KEY}" \
-X POST \
'http://${RANCHER_URL}:8080/v2-beta/projects/${PROJECT_ID}/hosts/${ID}?action=dockersocket'


Output: An updated copy of the hostAccess resource

error POST: /v2-beta/projects/${PROJECT_ID}/hosts/${ID}?action=error


Input:This action has no inputs


curl -u "${RANCHER_ACCESS_KEY}:${RANCHER_SECRET_KEY}" \
-X POST \
'http://${RANCHER_URL}:8080/v2-beta/projects/${PROJECT_ID}/hosts/${ID}?action=error'


Output: An updated copy of the host resource

evacuate POST: /v2-beta/projects/${PROJECT_ID}/hosts/${ID}?action=evacuate


Input:This action has no inputs


curl -u "${RANCHER_ACCESS_KEY}:${RANCHER_SECRET_KEY}" \
-X POST \
'http://${RANCHER_URL}:8080/v2-beta/projects/${PROJECT_ID}/hosts/${ID}?action=evacuate'


Output: An updated copy of the host resource