Projects¶
Within an organization, you can create projects to logically group infrastructure and to enable certain networking features.
Creating a Project¶
Owners and Admins of an Organization can create new projects. From an Organization's Projects tab. Click + Add New.
You can create a new Project with the metal project create command. Specify the name of the new project with the --name flag. Optionally specify which organization to create the project in with the --organization-id flag.
metal project create --name <string> --organization-id <org_UUID>
You can create a new Project by sending a POST request to the /projects endpoint.
curl -X POST \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/projects/" \
-d '{
"customdata": { },
"name": "string",
"organization_id": "<uuid>",
"payment_method_id": "<uuid>"
}'
"name" is the only required field in the body of the request.
Project Settings¶
General information about a project is on the General tab, including the project name and ID. Each project has a unique ID, which is used to reference the project in the API and allows it to be renamed at any time.
Project Settings is where you can:
- Rename the project.
- Mange the project's API keys and SSH keys.
- Access the project's Timeline.
- Monitor the project's Usage.
If you a Collaborator on a project, then you are also able to leave the project. If you are the Owner or Admin of the organization the project belongs to, then you have the option to delete the project.
SSH Keys¶
On the SSH tab, you can add Project-level SSH keys to allow SSH access to project's servers that is not tied to a particular user.
Project SSH keys will be deployed to new servers the same way that user SSH keys are. Any project collaborator can add and remove project-level SSH keys.
Add an SSH key to a project by sending a POST request to the /projects/{id}/ssh-keys endpoint.
curl -X POST \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/projects/{id}/ssh-keys" \
-d '{
"label": "my machine ssh key",
"key": "ssh-rsa....."
}'
To list all the project's SSH keys, send a GET request to the /projects/{id}/ssh-keys endpoint.
curl -X GET -H 'X-Auth-Token: <API_TOKEN>' \
"https://api.equinix.com/metal/v1/projects/{id}/ssh-keys"
General documentation on generating and using SSH Keys is on the SSH Keys page.
API Keys¶
On the API Keys tab, you can add a Project API key to allow access to the Equinix Metal API that is not tied to a particular user.
To create a Project API key, send a POST request to the /projects/{id}/api-keys endpoint.
curl -X POST \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/projects/{id}/api-keys" \
-d '{
"description": "string",
"read_only": true
}'
To list all the project's API keys, send a GET request to the /projects/{id}/api-keys endpoint.
curl -X GET -H 'X-Auth-Token: <API_TOKEN>' \
"https://api.equinix.com/metal/v1/projects/{id}/api-keys"
Note: Project API keys do not have access to the entirety of the API; some endpoints can only be used by personal API keys.
Project-level Infrastructure¶
All servers and infrastructure on Equinix Metal are provisioned as part of a project. On the project's main page you can see the categories managed at the project level in the Servers, IPs & Networks, and Storage tabs.
Bare Metal Servers¶
Under Bare Metal Servers is where you can provision and manage servers using the Equinix Metal console, with the option to deploy On Demand servers and manage your Reserved Hardware.
You can view and manage any servers that are currently in your Project from the Manage Servers page.
Networking¶
Under Networking is where you can provision and manage your Project's networking infrastructure, including:
Interconnections¶
Under Interconnections, you can provision and manage Fabric Virtual Connections and Dedicated Ports. These allow you to expand and connect your Equinix Metal Layer 2 networks across Equinix Fabric to other Cloud Service Providers or to your colocated infrastructure.
More information is available in the Interconnections documentation.
Users and Projects¶
You can manage which users have access to projects from your Organization Settings. Users that are a members of your organization and, specifically, users that have the Collaborator role can be assigned access to projects on a project-by-project basis. Collaborators on a project are permitted to access, provision and manage its servers.
Inviting a User to a Project¶
You invite a user to become a part of your project when you add them to your organization.
You can also invite a user to a project through the API, by sending a POST request to the /projects/{project_id}/invitations endpoint.
curl -X POST \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/projects/{project_id}/invitations" \
-d `{
"invitee": "user@example.com",
"message": "string",
"organization_id": "<uuid>",
"projects_ids": [
"<uuid>"
],
"roles": [
"collaborator"
]
}`
A list of invitations for a project can be retrieved by a GET request to the /projects/{project_id}/invitations endpoint.
curl -X GET -H 'X-Auth-Token: <API_TOKEN>' \
"https://api.equinix.com/metal/v1/projects/{project_id}/invitations"
Documentation on organizations and organization-level operations is on the Organizations page.
Transferring a Project¶
If you are an Owner of the organization a project belongs to, you can transfer the project to another organization.
First, you need ID of the Organization you want to transfer the project to, which can be found in its General settings tab.
Next, open the Project you are transferring, and navigate to the Project Settings and General tab. Note, if you are not the owner of the Organization, the project transfer options will not appear in the console.
In the Transfer Project To Another Workspace section paste transfer target Organization ID into the field. Click Transfer to send the transfer request to the target Organization.
To initiate a transfer through the API, send a POST request to the /projects/{id}/transfers endpoint. The ID of the receiving organization is a required body parameter.
curl -X POST \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/projects/{project_id}/transfers" \
-d '{
"target_organization_id": "<organization_uuid>"
}'
The response contains an ID for the transfer request, which is used to retrieve, accept, or decline the transfer.
Once the transfer is requested, the Owner of the receiving Organization will get an email notifying them of the transfer. They will have to accept the transfer to complete the process.
Managing Project Transfers¶
To view in-progress transfers, open the original Organizations Projects tab. If you have projects being transferred that have not been accepted by the receiving Organization, you have the option to Withdraw Transfer.
In the receiving Organization, the Projects tab contains a message where the transfer can be accepted or rejected. Click Accept on the requested transfer prompt.
To decline the transfer, click Reject.
To see the details of an in-progress transfer, send a GET request to the /transfers/{id} endpoint, with the ID of the request in the path.
curl -X GET -H 'X-Auth-Token: <API_TOKEN>' \
https://api.equinix.com/metal/v1/transfers/{id}
To accept a transfer request, send a PUT request to the /transfers/{id} endpoint, with the ID of the request in the path.
curl -X PUT -H 'X-Auth-Token: <API_TOKEN>' \
https://api.equinix.com/metal/v1/transfers/{id}
To decline a transfer request, send a DELETE request to the /transfers/{id} endpoint.
curl -X DELETE -H 'X-Auth-Token: <API_TOKEN>' \
https://api.equinix.com/metal/v1/transfers/{id}
Deleting a Project¶
Deleting an project is permanent.
Owners or Admins of the organization that owns the project are the only users that can delete a project. You can't delete a project that has active resources. You have to deprovision all servers and other infrastructure from a project in order to delete it.
You can delete a project from the Project Settings, on the General tab.
Click Delete Project and confirm on the confirmation dialog.
To delete a project in the CLI, use the metal project delete command.
metal project delete --id <project_UUID>
In the API, you can delete an organization by sending a DELETE request to the /projects/{id} endpoint.
curl -X DELETE -H 'X-Auth-Token: <API_TOKEN>' \
"https://api.equinix.com/metal/v1/projects/{project_id}"
Once a project is deleted, it will not accrue additional Usage. Any outstanding usage charges are billed to the organization at the end of the billing cycle.