Add a Physical Data Center connector

Connect Harness to hosts in your physical data center for traditional deployments.

Use a Harness Physical Data Center (PDC) connector to connect Harness to the hosts in your physical data center. PDC connectors are typically used for traditional deployments, including SSH and WinRM deployments.

What you will learn from this topic

How to create a Physical Data Center connector using the Harness Manager.
How to create a Physical Data Center connector using the API.
How to specify target hosts manually or using a JSON hosts file.
How to define a Physical Data Center connector using a YAML example.

Before you begin

Target hosts: The domain name or IP address of each host you want Harness to connect to, reachable from your Harness Delegate.
Harness Delegate: A running Harness Delegate that can reach the target hosts. Go to Delegate installation overview to install one.

Create a Physical Data Center connector

Perform the following steps to create the PDC connector using the Harness Manager. The connector wizard has four steps: Overview, Details, Delegates Setup, and Test Connection.

Overview

In your project, org, or account, select Connectors, and then select New Connector.
Select Physical Data Center.
Enter a Name for the connector. Harness automatically creates an Id (entity identifier) based on the Name.
Optionally, add a Description and Tags.
Select Continue to proceed to Details.

Details

Select Manually enter host names or Upload JSON file to define your list of hosts. For details on both options, go to Specify target hosts.
Select Continue to proceed to Delegates Setup.

Delegates Setup

Select Use any available Delegate, or select Only use Delegates with all of the following tags and enter one or more delegate tags.
Select Save and Continue to proceed to Test Connection.

Test Connection

Harness validates connectivity to the PDC hosts. If verification succeeds, select Finish.

Create a Physical Data Center connector using the API

Create the PDC connector using the Create a Connector API. The request sends the connector definition as YAML in the request body.

Create Connector API request

curl --location --request POST 'https://app.harness.io/gateway/ng/api/connectors?accountIdentifier=<YOUR_ACCOUNT_ID>' \
--header 'Content-Type: text/yaml' \
--header 'x-api-key: <YOUR_API_KEY>' \
--data-raw 'connector:
  name: PDC-Connector
  identifier: PDCConnector
  description: ""
  orgIdentifier: default
  projectIdentifier: CD_Docs
  type: Pdc
  spec:
    hosts:
      - hostname: ec2-54-111-26-183.us-west-2.compute.amazonaws.com
      - hostname: ec2-54-222-142-249.us-west-2.compute.amazonaws.com'

The request uses the following query parameter, headers, and body fields.

accountIdentifier (query parameter, required): The identifier of the Harness account where the connector is created. Replace <YOUR_ACCOUNT_ID> with your account identifier.
Content-Type (header, required): Set to text/yaml because the request body is YAML. Use application/json instead if you send the connector definition as JSON.
x-api-key (header, required): A Harness API key with permission to create connectors in the target scope. Replace <YOUR_API_KEY> with your API key. For details on creating one, go to Add and manage API keys.
connector.name: The connector display name shown in the Harness UI.
connector.identifier: A unique identifier for the connector. You cannot change the identifier after creation. For the identifier format, go to the Entity Identifier reference.
connector.description: An optional description for the connector.
connector.orgIdentifier: The identifier of the organization that owns the connector. Omit this field to create the connector at the account scope.
connector.projectIdentifier: The identifier of the project that owns the connector. Omit this field to create the connector at the account or organization scope. A project-scoped connector requires orgIdentifier as well.
connector.type: The connector type. Use Pdc for a Physical Data Center connector.
connector.spec.hosts: The list of target hosts for the connector. Each entry sets hostname to the target host's domain name or IP address. To add hosts using a JSON hosts file instead of a static list, go to Specify target hosts.

Specify target hosts

Add target hosts to the connector manually or by uploading a JSON hosts file.

Manually enter host names

To manually enter hosts in the connector, select Manually enter host names, and then add each host's domain name or IP address on a new line in the Hosts field.

JSON hosts file

The following JSON hosts file defines two hosts, each with a set of host attributes.

[
    {
        "hostname": "ec2-54-87-11-191.compute-1.amazonaws.com:5986",
        "hostAttributes": {
            "type": "node",
            "region": "east",
            "name": "node1",
            "ip": "54.87.11.191"
        }
    },
    {
        "hostname": "ec2-3-83-219-167.compute-1.amazonaws.com:5986",
        "hostAttributes": {
            "type": "db",
            "region": "east",
            "name": "node2",
            "ip": "3.83.219.167"
        }
    }
]

The hostname and hostAttributes properties are mandatory, and hostAttributes can have as many key-value pairs as you need.

When you select this PDC connector in an infrastructure definition, you can select Filter by host name or Filter by host attributes to select the hosts for deployment. Specify the host attributes as a comma-separated list of attribute:value pairs, for example, region:west,type:node.

YAML examples

The following YAML defines an account-scoped PDC connector with two target hosts, each with a set of host attributes.

PDC connector YAML

connector:
  name: PDC-Connector # Connector display name shown in the Harness UI
  identifier: PDCConnector # Unique connector identifier, cannot be changed after creation
  description: "" # Optional description for the connector
  accountIdentifier: <YOUR_ACCOUNT_ID> # Harness account identifier that owns the connector
  type: Pdc
  spec:
    ignoreTestConnection: false # Set to true to skip the connection test for hosts that are unreachable when the connector is saved
    hosts:
      - hostname: ec2-54-88-193-136.compute-1.amazonaws.com:5986 # Target host domain name or IP address, plus port if required
        hostAttributes: # Optional key-value pairs used to filter hosts during deployment
          type: node
          region: east
          name: node1
          ip: 54.88.193.136
      - hostname: ec2-54-225-189-86.compute-1.amazonaws.com:5986
        hostAttributes:
          type: db
          region: east
          name: node2
          ip: 54.225.189.86

The accountIdentifier field scopes the connector to the account level. Omit accountIdentifier and add orgIdentifier and, optionally, projectIdentifier instead to scope the connector to an organization or project. By default, ignoreTestConnection is false, and Harness tests the connection to each host when you save the connector.

Troubleshooting

Test Connection fails with a socket connectivity error for every host

The Test Connection step fails with an error similar to the following, and the delegate task logs show an UnknownHostException for each line of the host list, including JSON syntax such as {, }, and property names:

Invalid request: Socket connectivity checks failed for host(s)

This happens when the contents of a JSON hosts file are pasted directly into the Hosts field on the Details step instead of being uploaded as a file. Harness treats each line of the pasted text as a separate hostname.

To fix this, go back to the Details step, clear the Hosts field, select Upload JSON file, and upload the JSON hosts file instead of pasting its contents.

If this error occurs for a host you entered correctly, the delegate cannot establish a socket connection to the host. If you do not specify a port with the host, Harness defaults to port 22.

Verify the port is open on the host, and check the firewall rules between the delegate and the host.
Test connectivity from the delegate to the host using telnet <host> <port>.

Next steps

SSH deployments: Deploy artifacts to hosts using SSH.
WinRM deployments: Deploy artifacts to Windows hosts using WinRM.

PreviousKubernetes cluster connector settings reference

NextAdd a Rancher cluster connector

Last updated 12 days ago

Was this helpful?