Runner SSH Key Management Service

Audience

This article is to support customers of Runner, a product that enables teams, developers, and engineers to quickly provision, interact, and modify their environments anywhere - CenturyLink Cloud, third-party cloud providers, and on-premises. Additionally, the responses in this FAQ document are specific to using the service through the Control Portal.

SSH Key Management Service Overview

Runner’s SSH Key Management Service will help you to manage and deploy SSH credentials on CenturyLink Cloud servers. With the keys deployed from this service, you can securely create and execute tasks using our Job service. The job actions can be performed via REST API calls. The API works with JSON messages over HTTP. It relies on the standard HTTP verbs including GET, POST, PUT, and DELETE.

The URL format of the service is: https://api.runner.ctl.io/keypairs/{accountAlias}.

For example, to retrieve information of all deployed keypairs created at the account alias level, you would issue a GET request to https://api.runner.ctl.io/keypairs/ALIAS. Below are the various features of the service:

Create Keypair
Delete Keypair
Deploy Keypair
Get Keypair
Deploy Keypair to Server Users
Get Server Users
Get Keypairs
Undeploy Keypair for Server Users

CREATE KEYPAIR

Creates an SSH Keypair and allows you to deploy those credentials to CenturyLink servers in your account. The key can then be used to authenticate to these resources when executing a Runner Job. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to use it

Use this API operation when you would like to create, deploy and manage SSH keys on CenturyLink servers.

Note: The SSH privateKey is generated only once, so you have to save the privateKey from the response.

URL

Structure

POST https://api.runner.ctl.io/keypairs/{accountAlias}/{keypairAlias}

Example

POST https://api.runner.ctl.io/keypairs/XXXX/TestGroup

Request

URI Parameters

NAME	TYPE	DESCRIPTION	REQ.
accountAlias	string	Short code for a particular account.	Yes
keypairAlias	string	Categorize and manage your keys with an alias name.	Yes

Content Properties

NAME	TYPE	DESCRIPTION	REQ.
deployToServers	array	Array list of servers and their user names.	No

Server Entity

NAME	TYPE	DESCRIPTION
serverId	string	Server ID for which the key(s) to be deployed.
usernames	array	Array of server usernames to be authorized with the key.

"deployToServers": [
    {
        "serverId": "UC1ACCTUBUSVR04",
        "usernames": ["username1", "username2"]
    }
  ]

Example

{
    "deployToServers": [
        {
            "serverId": "UC1ACCTUBUSVR04",
            "usernames": [ "root"]
        }
    ]
}

Response

The response will be an object with the created SSH key information deployed on the specified server(s).

Entity Definition

NAME	TYPE	DESCRIPTION
alias	string	The custom alias name provided to categorize your keys.
privateKey	string	The SSH privateKey is generated only once, so you have to save the privateKey for future reference.
publicKey	string	The SSH publicKey deployed on the specified server(s).
fingerprint	string	ECDSA key fingerprint.
deployedServers	array	Array list of servers and their user names.

Server Entity

NAME	TYPE	DESCRIPTION
serverId	string	Server ID for which the key(s) is deployed.
usernames	array	Array of server usernames to be authorized with the key.

Example

{
  "alias": "TestGroup",
  privateKey: "-----BEGIN RSA PRIVATE KEY----- XIEOASASAS......M7ezqzt3jM0aA== -----END RSA PRIVATE KEY----- "
  "publicKey": "ssh-rsa CYXYXHXY3NzaC1yc2.....Ug42vKgh abc.def@fghijk.com",
  fingerprint: "6d:3e:d2:6a.....e:e0:bf:20:0c",
  "deployedServers": [
    {
      "serverId": "UC1ACCTUBUSVR04",
      "usernames": ["root"]
    }
  ]
}

DELETE KEYPAIR

Delete deployed SSH credentials to CenturyLink servers. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to use it

Use this API operation when you would like to remove a deployed key pair from your CenturyLink Cloud account alias.

URL

Structure

DELETE https://api.runner.ctl.io/keypairs/{accountAlias}/{keypairAlias}

Example

DELETE https://api.runner.ctl.io/keypairs/XXXX/TestGroup

Request

URI Parameters

NAME	TYPE	DESCRIPTION	REQ.
accountAlias	string	Short code for a particular account.	Yes
keypairAlias	string	The keypair alias name that you would like to delete.	Yes

Example

https://api.runner.ctl.io/keypairs/XXXX/TestGroup

Response

The response will be a standard HTTP 200 OK response upon deletion of the keypair.

DEPLOY KEYPAIR

Deploys SSH credentials to CenturyLink Cloud servers in a given account, so the keys can be used to authenticate these servers when executing Runner jobs. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to use it

Use this API operation when you would like to manage and deploy SSH keys to machines involved in a Runner job.

URL

Structure

PUT https://api.runner.ctl.io/keypairs/{accountAlias}/{keypairAlias}

Example

PUT https://api.runner.ctl.io/keypairs/XXXX/TestGroup

Request

URI Parameters

NAME	TYPE	DESCRIPTION	REQ.
accountAlias	string	Short code for a particular account.	Yes
keypairAlias	string	Your keypair alias name.	Yes

Content Properties

NAME	TYPE	DESCRIPTION	REQ.
deployToServers	array	Array list of servers and their user names.	Yes
publicKey	string	The SSH publicKey to be deployed for the servers.	Yes

Server Entity

NAME	TYPE	DESCRIPTION
serverId	string	Server ID for which the key to be deployed.
usernames	array	Array of server usernames to be authorized with the key.

"deployToServers": [
    {
        "serverId": "UC1ACCTUBUSVR04",
        "usernames": ["username1", "username2"]
    }

Example

{
    "deployToServers": [
        {
            "serverId": "UC1ACCTUBUSVR04",
            "usernames": [ "root"]
        }
    ],
    "publicKey" : "ssh-rsa CYXYXHXY3NzaC1yc2EAA.......mYr9triUlZNSx0Ug42vKgh abc.def@fghijk.com"
}

Response

The response will be an object with the key deployed to servers.

Entity Definition

NAME	TYPE	DESCRIPTION
alias	string	The custom alias name provided to categorize your keys.
publicKey	string	The SSH publicKey deployed for the servers.
deployedServers	array	Array list of servers and their user names

Server Entity

NAME	TYPE	DESCRIPTION
serverId	string	Server ID for which the key(s) is deployed.
usernames	array	Array of server usernames to be authorized with the key.

Example

{
  "alias": "TestGroup",
  "publicKey": "ssh-rsa CYXYXHXY3NzaC1yc2EAAAADA.........riUlZNSx0Ug42vKgh abc.def@fghijk.com",
  "deployedServers": [
    {
      "serverId": "UC1ACCTUBUSVR04",
      "usernames": ["root"]
    }
  ]
}

GET KEYPAIR

Retrieve the details of an existing keypair alias. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to use it

Use this API operation when you would like to retrieve the details of a deployed key pair to your CenturyLink Cloud account alias.

URL

Structure

GET https://api.runner.ctl.io/keypairs/{accountAlias}/{keypairAlias}

Example

GET https://api.runner.ctl.io/keypairs/XXXX/TestGroup

Request

URI Parameters

NAME	TYPE	DESCRIPTION	REQ.
accountAlias	string	Short code for a particular account.	Yes
keypairAlias	string	Your keypair alias name.	Yes

Example

https://api.runner.ctl.io/keypairs/XXXX/TestGroup

Response

The response will be an object with the key deployed to servers.

Entity Definition

NAME	TYPE	DESCRIPTION
alias	string	The custom alias name provided to categorize your keys.
publicKey	string	The SSH publicKey deployed for the servers.
deployedServers	array	Array list of servers and their user names.

Server Entity

NAME	TYPE	DESCRIPTION
serverId	string	Server ID for which the key(s) is deployed.
usernames	array	Array of server usernames to be authorized with the key.

Example

{
    alias: "TestGroup"
    publicKey: "ssh-rsa CYXYXHXY3NzaC1yc.........Ug42vKgh abc.def@fghijk.com"
    deployedServers: [
    {
        serverId: "UC1ACCTUBUSVR04"
        usernames: ["root"]
    },
    {
        serverId: "UC1ACCTUBUSVR05"
        usernames: ["root"]
    }
}

DEPLOY KEYPAIR TO SERVER USERS

Add server users for a deployed SSH keypair. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to use it

Use this API operation when you would like to add server users to an already deployed key pair.

URL

Structure

POST https://api.runner.ctl.io/keypairs/{accountAlias}/{keypairAlias}/{serverId}

Example

POST https://api.runner.ctl.io/keypairs/XXXX/TestGroup/UC1ACCTUBUSVR04

Request

URI Parameters

NAME	TYPE	DESCRIPTION	REQ.
accountAlias	string	Short code for a particular account.	Yes
keypairAlias	string	Your keypair alias name.	Yes
serverId	string	Server ID for which the key(s) is/are deployed.	Yes

Content Properties

NAME	TYPE	DESCRIPTION	REQ.
usernames	array	Array of additional server usernames to be authorized with the key.	Yes

Example

{
    "usernames": ["admin"]
}

Response

The response will be a standard HTTP 200 OK response upon new server user name addition.

GET SERVER USERS

Get server usernames for a deployed SSH keypair. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to use it

Use this API operation when you would like to get the list of usernames (of a specific server) for deployed key pairs.

URL

Structure

GET https://api.runner.ctl.io/keypairs/{accountAlias}/{keypairAlias}/{serverId}

Example

GET https://api.runner.ctl.io/keypairs/XXXX/TestGroup/UC1ACCTUBUSVR04

Request

URI Parameters

NAME	TYPE	DESCRIPTION	REQ.
accountAlias	string	Short code for a particular account.	Yes
keypairAlias	string	Your keypair alias name.	Yes
serverId	string	Server ID for which the key(s) is deployed.	Yes

Example

https://api.runner.ctl.io/keypairs/XXXX/TestGroup/UC1ACCTUBUSVR04

Response

The response will be server usernames (listed as array of string) for a deployed SSH keypair.

["root"]

GET KEYPAIRS

To get the details of all deployed SSH credentials to CenturyLink servers. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to use it

Use this API operation when you would like to retrieve the details of all deployed key pair to your CenturyLink account alias.

URL

Structure

GET https://api.runner.ctl.io/keypairs/{accountAlias}

Example

GET https://api.runner.ctl.io/keypairs/XXXX

Request

URI Parameters

NAME	TYPE	DESCRIPTION	REQ.
accountAlias	string	Short code for a particular account.	Yes

https://api.runner.ctl.io/keypairs/XXXX/TestGroup

Response

The response will be list of objects (based on keypair alias) that were created within CenturyLink Cloud account alias.

Entity Definition

NAME	TYPE	DESCRIPTION
alias	string	The custom alias name provided to categorize your keys.
publicKey	string	The SSH publicKey deployed for the servers.
deployedServers	array	Array list of servers and their user names.

Server Entity

NAME	TYPE	DESCRIPTION
serverId	string	Server ID for which the key(s) is deployed.
usernames	array	Array of server usernames to be authorized with the key.

[
    {
        alias: "TestGroup"
        publicKey: "ssh-rsa CYXYXHXY3NzaC1yc2E......iUlZNSx0Ug42vKgh abc.def@fghijk.com"
        deployedServers: [
        {
            serverId: "UC1ACCTUBUSVR04"
            usernames: ["root"]
        },
        {
            serverId: "UC1ACCTUBUSVR05"
            usernames: ["root"]
        }
    },
    {
        alias: "ProdGroup"
        publicKey: "ssh-rsa DZZZYXHXY3NzaC1yc2EAAA......NSx0Ug42vKgh abc.def@fghijk.com"
        deployedServers: [
        {
            serverId: "UC1PRODUBUSVR04"
            usernames: ["root"]
        },
        {
            serverId: "UC1PRODUBUSVR05"
            usernames: ["root"]
        }
    }
]

UNDEPLOY KEYPAIR FOR SERVER USERS

Undeploy key pair for a specific server user. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to use it

Use this API operation when you would like to undeployed a key pair for certain server users.

URL

Structure

DELETE https://api.runner.ctl.io/keypairs/{accountAlias}/{keypairAlias}/{serverId}

Example

DELETE https://api.runner.ctl.io/keypairs/XXXX/TestGroup/UC1ACCTUBUSVR04

Request

URI Parameters

NAME	TYPE	DESCRIPTION	REQ.
accountAlias	string	Short code for a particular account.	Yes
keypairAlias	string	Your keypair alias name.	Yes
serverId	string	Server ID for which the key has to be undeployed for a specific user(s).	Yes

Content Properties

NAME	TYPE	DESCRIPTION	REQ.
usernames	array	Array of server usernames for which the keys have to be undeployed.	Yes

Example

{
    "usernames": ["admin"]
}

Response

The response will be a standard HTTP 200 OK response upon key has been undeployed for the server user name.

Cloud Management Manage complex cloud solutions from a single platform with Cloud Application Manager.

Infrastructure & Compute Access and control high-performing virtual and physical machines.

Compute

Storage

Networking Increased reliability and faster performance in the cloud.

Managed Services Save time and increase productivity with management from CenturyLink’s highly-skilled team.

Application Services Manage and provision faster and more efficiently.

Database

Services

Platform Services

Cloud Reseller Program Become a Reseller and fast-track your ability to offer white-labeled enterprise cloud services.

Subscribe to CenturyLink Cloud Knowledge Base