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

Content Properties

Server Entity

"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

Server Entity

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

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

Content Properties

Server Entity

"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

Server Entity

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

Example

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

Response

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

Entity Definition

Server Entity

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

Content Properties

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

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

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

Server Entity

[
    {
        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

Content Properties

Example

{
    "usernames": ["admin"]
}

Response

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