Service

Rancher adopts the standard Docker Compose terminology for services and defines a basic service as one or more containers created from the same Docker image. Once a service (consumer) is linked to another service (producer) within the same stack, a DNS record mapped to each container instance is automatically created and discoverable by containers from the “consuming” service. Other benefits of creating a service under Rancher include”

Resource Fields

Writeable Fields

Field Type Create Update Default Notes
assignServiceIpAddress boolean Optional - -  
description string Optional Yes -  
externalId string Optional - -  
launchConfig launchConfig Optional - -  
lbConfig lbTargetConfig Optional Yes -  
metadata map[json] Optional Yes -  
name string Yes Yes -  
publicEndpoints array[publicEndpoint] Optional Yes -  
retainIp boolean Optional Yes -  
scale int Optional Yes 1  
scalePolicy scalePolicy Optional Yes -  
secondaryLaunchConfigs array[secondaryLaunchConfig] Optional - -  
selectorContainer string Optional Yes -  
selectorLink string Optional Yes -  
stackId stack Optional - -  
startOnCreate boolean Optional - -  
vip string Optional - -  

Read Only Fields

Field Type Notes
createIndex int  
currentScale int  
fqdn string  
healthState string  
id int The unique identifier for the service
instanceIds array[instance]  
linkedServices map[service]  
system boolean  
upgrade serviceUpgrade  


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}/services

curl -u "${RANCHER_ACCESS_KEY}:${RANCHER_SECRET_KEY}" \
-X POST \
-H 'Content-Type: application/json' \
-d '{
	"assignServiceIpAddress": false,
	"description": "string",
	"externalId": "string",
	"launchConfig": {
		"accountId": "reference[account]",
		"blkioDeviceOptions": "map[blkioDeviceOption]",
		"blkioWeight": 0,
		"build": {
			"context": "string",
			"dockerfile": "string",
			"forcerm": false,
			"nocache": false,
			"remote": "string",
			"rm": false
		},
		"capAdd": "array[enum]",
		"capDrop": "array[enum]",
		"cgroupParent": "string",
		"command": [
			"string1",
			"...stringN"
		],
		"count": 0,
		"cpuCount": 0,
		"cpuPercent": 0,
		"cpuPeriod": 0,
		"cpuQuota": 0,
		"cpuSet": "string",
		"cpuSetMems": "string",
		"cpuShares": 0,
		"createIndex": 0,
		"created": "date",
		"dataVolumeMounts": "map[reference[volume]]",
		"dataVolumes": [
			"string1",
			"...stringN"
		],
		"dataVolumesFrom": "array[reference[container]]",
		"dataVolumesFromLaunchConfigs": [
			"string1",
			"...stringN"
		],
		"deploymentUnitUuid": "string",
		"description": "string",
		"devices": [
			"string1",
			"...stringN"
		],
		"diskQuota": 0,
		"disks": "array[virtualMachineDisk]",
		"dns": [
			"string1",
			"...stringN"
		],
		"dnsOpt": [
			"string1",
			"...stringN"
		],
		"dnsSearch": [
			"string1",
			"...stringN"
		],
		"domainName": "string",
		"entryPoint": [
			"string1",
			"...stringN"
		],
		"environment": {
			"key": "value-pairs"
		},
		"expose": [
			"string1",
			"...stringN"
		],
		"externalId": "string",
		"extraHosts": [
			"string1",
			"...stringN"
		],
		"firstRunning": "date",
		"groupAdd": [
			"string1",
			"...stringN"
		],
		"healthCheck": {
			"healthyThreshold": 0,
			"initializingTimeout": 0,
			"interval": 0,
			"name": "string",
			"port": 0,
			"recreateOnQuorumStrategyConfig": {
				"quorum": 0
			},
			"reinitializingTimeout": 0,
			"requestLine": "string",
			"responseTimeout": 0,
			"strategy": "recreate",
			"unhealthyThreshold": 0
		},
		"healthCmd": [
			"string1",
			"...stringN"
		],
		"healthInterval": 0,
		"healthRetries": 0,
		"healthState": "enum",
		"healthTimeout": 0,
		"hostId": "reference[host]",
		"hostname": "string",
		"id": 0,
		"imageUuid": "string",
		"instanceLinks": "map[reference[instance]]",
		"instanceTriggeredStop": "stop",
		"ioMaximumBandwidth": 0,
		"ioMaximumIOps": 0,
		"ip": "string",
		"ip6": "string",
		"ipcMode": "string",
		"isolation": "string",
		"kernelMemory": 0,
		"kind": "container",
		"labels": {
			"key": "value-pairs"
		},
		"logConfig": {
			"config": {
				"key": "value-pairs"
			},
			"driver": "string"
		},
		"lxcConf": {
			"key": "value-pairs"
		},
		"memory": 0,
		"memoryMb": 0,
		"memoryReservation": 0,
		"memorySwap": 0,
		"memorySwappiness": 0,
		"milliCpuReservation": 0,
		"mounts": "array[mountEntry]",
		"nativeContainer": false,
		"netAlias": [
			"string1",
			"...stringN"
		],
		"networkContainerId": "reference[container]",
		"networkIds": "array[reference[network]]",
		"networkLaunchConfig": "string",
		"networkMode": "managed",
		"oomKillDisable": false,
		"oomScoreAdj": 0,
		"pidMode": "enum",
		"pidsLimit": 0,
		"ports": [
			"string1",
			"...stringN"
		],
		"primaryIpAddress": "string",
		"primaryNetworkId": "reference[network]",
		"privileged": false,
		"publishAllPorts": false,
		"readOnly": false,
		"registryCredentialId": "reference[registryCredential]",
		"removed": "date",
		"requestedHostId": "reference[host]",
		"requestedIpAddress": "string",
		"secrets": "array[secretReference]",
		"securityOpt": [
			"string1",
			"...stringN"
		],
		"serviceId": "reference[service]",
		"serviceIds": "array[reference[service]]",
		"shmSize": 0,
		"stackId": "reference[stack]",
		"startCount": 0,
		"startOnCreate": true,
		"state": "enum",
		"stdinOpen": false,
		"stopSignal": "string",
		"storageOpt": {
			"key": "value-pairs"
		},
		"sysctls": {
			"key": "value-pairs"
		},
		"system": false,
		"tmpfs": {
			"key": "value-pairs"
		},
		"transitioning": "enum",
		"transitioningMessage": "string",
		"transitioningProgress": 0,
		"tty": false,
		"ulimits": "array[ulimit]",
		"user": "string",
		"userPorts": [
			"string1",
			"...stringN"
		],
		"userdata": "string",
		"usernsMode": "string",
		"uts": "string",
		"uuid": "string",
		"vcpu": 1,
		"version": "0",
		"volumeDriver": "string",
		"workingDir": "string"
	},
	"lbConfig": {
		"portRules": "array[targetPortRule]"
	},
	"metadata": {
		"key": "value-pairs"
	},
	"name": "string",
	"publicEndpoints": "array[publicEndpoint]",
	"retainIp": false,
	"scale": 1,
	"scalePolicy": {
		"increment": 1,
		"max": 1,
		"min": 1
	},
	"secondaryLaunchConfigs": "array[secondaryLaunchConfig]",
	"selectorContainer": "string",
	"selectorLink": "string",
	"stackId": "reference[stack]",
	"startOnCreate": false,
	"vip": "string"
}' 'http://${RANCHER_URL}:8080/v2-beta/projects/${PROJECT_ID}/services'

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

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

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

curl -u "${RANCHER_ACCESS_KEY}:${RANCHER_SECRET_KEY}" \
-X PUT \
-H 'Content-Type: application/json' \
-d '{
	"description": "string",
	"lbConfig": {
		"portRules": "array[targetPortRule]"
	},
	"metadata": {
		"key": "value-pairs"
	},
	"name": "string",
	"publicEndpoints": "array[publicEndpoint]",
	"retainIp": false,
	"scale": 1,
	"scalePolicy": {
		"increment": 1,
		"max": 1,
		"min": 1
	},
	"selectorContainer": "string",
	"selectorLink": "string"
}' 'http://${RANCHER_URL}:8080/v2-beta/projects/${PROJECT_ID}/services/${ID}'

Actions

activate POST: /v2-beta/projects/${PROJECT_ID}/services/${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}/services/${ID}?action=activate'


Output: An updated copy of the service resource

cancelupgrade POST: /v2-beta/projects/${PROJECT_ID}/services/${ID}?action=cancelupgrade


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}/services/${ID}?action=cancelupgrade'


Output: An updated copy of the service resource

continueupgrade POST: /v2-beta/projects/${PROJECT_ID}/services/${ID}?action=continueupgrade


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}/services/${ID}?action=continueupgrade'


Output: An updated copy of the service resource

deactivate POST: /v2-beta/projects/${PROJECT_ID}/services/${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}/services/${ID}?action=deactivate'


Output: An updated copy of the service resource

finishupgrade POST: /v2-beta/projects/${PROJECT_ID}/services/${ID}?action=finishupgrade


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}/services/${ID}?action=finishupgrade'


Output: An updated copy of the service resource

restart POST: /v2-beta/projects/${PROJECT_ID}/services/${ID}?action=restart


Input: ServiceRestart

Field Type Required Default Notes
rollingRestartStrategy rollingRestartStrategy Yes    


curl -u "${RANCHER_ACCESS_KEY}:${RANCHER_SECRET_KEY}" \
-X POST \
-H 'Content-Type: application/json' \
-d '{
	"rollingRestartStrategy": {
		"batchSize": 1,
		"intervalMillis": 2000
	}
}' 'http://${RANCHER_URL}:8080/v2-beta/projects/${PROJECT_ID}/services/${ID}?action=restart'


Output: An updated copy of the service resource

rollback POST: /v2-beta/projects/${PROJECT_ID}/services/${ID}?action=rollback


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}/services/${ID}?action=rollback'


Output: An updated copy of the service resource

upgrade POST: /v2-beta/projects/${PROJECT_ID}/services/${ID}?action=upgrade


Input: ServiceUpgrade

Field Type Required Default Notes
inServiceStrategy inServiceUpgradeStrategy No    
toServiceStrategy toServiceUpgradeStrategy No    


curl -u "${RANCHER_ACCESS_KEY}:${RANCHER_SECRET_KEY}" \
-X POST \
-H 'Content-Type: application/json' \
-d '{
	"inServiceStrategy": {
		"batchSize": 1,
		"intervalMillis": 2000,
		"launchConfig": {
			"accountId": "reference[account]",
			"blkioDeviceOptions": "map[blkioDeviceOption]",
			"blkioWeight": 0,
			"build": {
				"context": "string",
				"dockerfile": "string",
				"forcerm": false,
				"nocache": false,
				"remote": "string",
				"rm": false
			},
			"capAdd": "array[enum]",
			"capDrop": "array[enum]",
			"cgroupParent": "string",
			"command": [
				"string1",
				"...stringN"
			],
			"count": 0,
			"cpuCount": 0,
			"cpuPercent": 0,
			"cpuPeriod": 0,
			"cpuQuota": 0,
			"cpuSet": "string",
			"cpuSetMems": "string",
			"cpuShares": 0,
			"createIndex": 0,
			"created": "date",
			"dataVolumeMounts": "map[reference[volume]]",
			"dataVolumes": [
				"string1",
				"...stringN"
			],
			"dataVolumesFrom": "array[reference[container]]",
			"dataVolumesFromLaunchConfigs": [
				"string1",
				"...stringN"
			],
			"deploymentUnitUuid": "string",
			"description": "string",
			"devices": [
				"string1",
				"...stringN"
			],
			"diskQuota": 0,
			"disks": "array[virtualMachineDisk]",
			"dns": [
				"string1",
				"...stringN"
			],
			"dnsOpt": [
				"string1",
				"...stringN"
			],
			"dnsSearch": [
				"string1",
				"...stringN"
			],
			"domainName": "string",
			"entryPoint": [
				"string1",
				"...stringN"
			],
			"environment": {
				"key": "value-pairs"
			},
			"expose": [
				"string1",
				"...stringN"
			],
			"externalId": "string",
			"extraHosts": [
				"string1",
				"...stringN"
			],
			"firstRunning": "date",
			"groupAdd": [
				"string1",
				"...stringN"
			],
			"healthCheck": {
				"healthyThreshold": 0,
				"initializingTimeout": 0,
				"interval": 0,
				"name": "string",
				"port": 0,
				"recreateOnQuorumStrategyConfig": {
					"quorum": 0
				},
				"reinitializingTimeout": 0,
				"requestLine": "string",
				"responseTimeout": 0,
				"strategy": "recreate",
				"unhealthyThreshold": 0
			},
			"healthCmd": [
				"string1",
				"...stringN"
			],
			"healthInterval": 0,
			"healthRetries": 0,
			"healthState": "enum",
			"healthTimeout": 0,
			"hostId": "reference[host]",
			"hostname": "string",
			"id": 0,
			"imageUuid": "string",
			"instanceLinks": "map[reference[instance]]",
			"instanceTriggeredStop": "stop",
			"ioMaximumBandwidth": 0,
			"ioMaximumIOps": 0,
			"ip": "string",
			"ip6": "string",
			"ipcMode": "string",
			"isolation": "string",
			"kernelMemory": 0,
			"kind": "container",
			"labels": {
				"key": "value-pairs"
			},
			"logConfig": {
				"config": {
					"key": "value-pairs"
				},
				"driver": "string"
			},
			"lxcConf": {
				"key": "value-pairs"
			},
			"memory": 0,
			"memoryMb": 0,
			"memoryReservation": 0,
			"memorySwap": 0,
			"memorySwappiness": 0,
			"milliCpuReservation": 0,
			"mounts": "array[mountEntry]",
			"nativeContainer": false,
			"netAlias": [
				"string1",
				"...stringN"
			],
			"networkContainerId": "reference[container]",
			"networkIds": "array[reference[network]]",
			"networkLaunchConfig": "string",
			"networkMode": "managed",
			"oomKillDisable": false,
			"oomScoreAdj": 0,
			"pidMode": "enum",
			"pidsLimit": 0,
			"ports": [
				"string1",
				"...stringN"
			],
			"primaryIpAddress": "string",
			"primaryNetworkId": "reference[network]",
			"privileged": false,
			"publishAllPorts": false,
			"readOnly": false,
			"registryCredentialId": "reference[registryCredential]",
			"removed": "date",
			"requestedHostId": "reference[host]",
			"requestedIpAddress": "string",
			"secrets": "array[secretReference]",
			"securityOpt": [
				"string1",
				"...stringN"
			],
			"serviceId": "reference[service]",
			"serviceIds": "array[reference[service]]",
			"shmSize": 0,
			"stackId": "reference[stack]",
			"startCount": 0,
			"startOnCreate": true,
			"state": "enum",
			"stdinOpen": false,
			"stopSignal": "string",
			"storageOpt": {
				"key": "value-pairs"
			},
			"sysctls": {
				"key": "value-pairs"
			},
			"system": false,
			"tmpfs": {
				"key": "value-pairs"
			},
			"transitioning": "enum",
			"transitioningMessage": "string",
			"transitioningProgress": 0,
			"tty": false,
			"ulimits": "array[ulimit]",
			"user": "string",
			"userPorts": [
				"string1",
				"...stringN"
			],
			"userdata": "string",
			"usernsMode": "string",
			"uts": "string",
			"uuid": "string",
			"vcpu": 1,
			"version": "0",
			"volumeDriver": "string",
			"workingDir": "string"
		},
		"previousLaunchConfig": {
			"accountId": "reference[account]",
			"blkioDeviceOptions": "map[blkioDeviceOption]",
			"blkioWeight": 0,
			"build": {
				"context": "string",
				"dockerfile": "string",
				"forcerm": false,
				"nocache": false,
				"remote": "string",
				"rm": false
			},
			"capAdd": "array[enum]",
			"capDrop": "array[enum]",
			"cgroupParent": "string",
			"command": [
				"string1",
				"...stringN"
			],
			"count": 0,
			"cpuCount": 0,
			"cpuPercent": 0,
			"cpuPeriod": 0,
			"cpuQuota": 0,
			"cpuSet": "string",
			"cpuSetMems": "string",
			"cpuShares": 0,
			"createIndex": 0,
			"created": "date",
			"dataVolumeMounts": "map[reference[volume]]",
			"dataVolumes": [
				"string1",
				"...stringN"
			],
			"dataVolumesFrom": "array[reference[container]]",
			"dataVolumesFromLaunchConfigs": [
				"string1",
				"...stringN"
			],
			"deploymentUnitUuid": "string",
			"description": "string",
			"devices": [
				"string1",
				"...stringN"
			],
			"diskQuota": 0,
			"disks": "array[virtualMachineDisk]",
			"dns": [
				"string1",
				"...stringN"
			],
			"dnsOpt": [
				"string1",
				"...stringN"
			],
			"dnsSearch": [
				"string1",
				"...stringN"
			],
			"domainName": "string",
			"entryPoint": [
				"string1",
				"...stringN"
			],
			"environment": {
				"key": "value-pairs"
			},
			"expose": [
				"string1",
				"...stringN"
			],
			"externalId": "string",
			"extraHosts": [
				"string1",
				"...stringN"
			],
			"firstRunning": "date",
			"groupAdd": [
				"string1",
				"...stringN"
			],
			"healthCheck": {
				"healthyThreshold": 0,
				"initializingTimeout": 0,
				"interval": 0,
				"name": "string",
				"port": 0,
				"recreateOnQuorumStrategyConfig": {
					"quorum": 0
				},
				"reinitializingTimeout": 0,
				"requestLine": "string",
				"responseTimeout": 0,
				"strategy": "recreate",
				"unhealthyThreshold": 0
			},
			"healthCmd": [
				"string1",
				"...stringN"
			],
			"healthInterval": 0,
			"healthRetries": 0,
			"healthState": "enum",
			"healthTimeout": 0,
			"hostId": "reference[host]",
			"hostname": "string",
			"id": 0,
			"imageUuid": "string",
			"instanceLinks": "map[reference[instance]]",
			"instanceTriggeredStop": "stop",
			"ioMaximumBandwidth": 0,
			"ioMaximumIOps": 0,
			"ip": "string",
			"ip6": "string",
			"ipcMode": "string",
			"isolation": "string",
			"kernelMemory": 0,
			"kind": "container",
			"labels": {
				"key": "value-pairs"
			},
			"logConfig": {
				"config": {
					"key": "value-pairs"
				},
				"driver": "string"
			},
			"lxcConf": {
				"key": "value-pairs"
			},
			"memory": 0,
			"memoryMb": 0,
			"memoryReservation": 0,
			"memorySwap": 0,
			"memorySwappiness": 0,
			"milliCpuReservation": 0,
			"mounts": "array[mountEntry]",
			"nativeContainer": false,
			"netAlias": [
				"string1",
				"...stringN"
			],
			"networkContainerId": "reference[container]",
			"networkIds": "array[reference[network]]",
			"networkLaunchConfig": "string",
			"networkMode": "managed",
			"oomKillDisable": false,
			"oomScoreAdj": 0,
			"pidMode": "enum",
			"pidsLimit": 0,
			"ports": [
				"string1",
				"...stringN"
			],
			"primaryIpAddress": "string",
			"primaryNetworkId": "reference[network]",
			"privileged": false,
			"publishAllPorts": false,
			"readOnly": false,
			"registryCredentialId": "reference[registryCredential]",
			"removed": "date",
			"requestedHostId": "reference[host]",
			"requestedIpAddress": "string",
			"secrets": "array[secretReference]",
			"securityOpt": [
				"string1",
				"...stringN"
			],
			"serviceId": "reference[service]",
			"serviceIds": "array[reference[service]]",
			"shmSize": 0,
			"stackId": "reference[stack]",
			"startCount": 0,
			"startOnCreate": true,
			"state": "enum",
			"stdinOpen": false,
			"stopSignal": "string",
			"storageOpt": {
				"key": "value-pairs"
			},
			"sysctls": {
				"key": "value-pairs"
			},
			"system": false,
			"tmpfs": {
				"key": "value-pairs"
			},
			"transitioning": "enum",
			"transitioningMessage": "string",
			"transitioningProgress": 0,
			"tty": false,
			"ulimits": "array[ulimit]",
			"user": "string",
			"userPorts": [
				"string1",
				"...stringN"
			],
			"userdata": "string",
			"usernsMode": "string",
			"uts": "string",
			"uuid": "string",
			"vcpu": 1,
			"version": "0",
			"volumeDriver": "string",
			"workingDir": "string"
		},
		"previousSecondaryLaunchConfigs": "array[secondaryLaunchConfig]",
		"secondaryLaunchConfigs": "array[secondaryLaunchConfig]",
		"startFirst": false
	},
	"toServiceStrategy": {
		"batchSize": 1,
		"finalScale": 1,
		"intervalMillis": 2000,
		"toServiceId": "reference[service]",
		"updateLinks": false
	}
}' 'http://${RANCHER_URL}:8080/v2-beta/projects/${PROJECT_ID}/services/${ID}?action=upgrade'


Output: An updated copy of the service resource