Skip to main content

Environments

Managing multiple virtual machines, volumes, and other resources can become challenging. To solve this issue, you can group your resources into resource containers called Environments. Environments are predefined user spaces that are created within a region, offering a logical way to organize your resources. All your resources, including SSH key pairs, virtual machines, volumes, etc., are created within a designated environment. It is possible to create multiple environments in the same region. These environments ensure the logical organization of your resources across multiple regions, providing seamless management and easy accessibility. Additionally, Environments are eligible for discounts.

User access to environments can be managed using our Role-Based Access Control (RBAC) system.
See more information about RBAC: Environment permissions.

In this article


OperationsEndpoints
Create a new EnvironmentPOST /core/environments
Retrieve a list of your environmentsGET /core/environments
Retrieve information about one of your environmentsGET /core/environments/{id}
Update the details of one of your environmentsPUT /core/environments/{id}
Delete an environmentDELETE /core/environments/{id}

Creating an environment

POST https://infrahub-api.nexgencloud.com/v1/core/environments

Creating an environment to organize your resources is a straightforward process. Select a name for the environment and specify a region where your resources will be stored. Include these values as parameters in the request body to get started.

See more information about choosing a region.


Request body parameters

The following parameters must be sent in the body of the request:


name REQUIRED string

The name of the environment being created.
A string with a maximum length of 50 characters.


region REQUIRED string

The geographic location of the data center where the environment is being created. Learn more about regions.
Possible enum values: NORWAY-1, CANADA-1


Returns


This response indicates that the creation of your environment named development in region NORWAY-1 has been successful. The environment object containing details on the created environment is returned if the request was successful, otherwise, an error is returned.


Attributes of the Environment object


status boolean

Indicates the success or failure of the operation. In this case, it is set to true, indicating that the environment has been created successfully.


message string

A message confirming the successful creation of the environment.


environment object

An object containing details about the created environment.

Show child attributes
id integer

Unique identifier for the environment.


name string

Name of the environment, e.g., "development."


region string

Name of the region associated with the environment, e.g., "NORWAY-1."


created_at date-time

Date and time when the environment was created, presented in ISO 8601 format.

Example request
curl -X POST "https://infrahub-api.nexgencloud.com/v1/core/environments" \
-H "accept: application/json"\
-H "api_key: YOUR API KEY"\
-H "content-type: application/json" \
-d '{
"name": "YOUR ENVIRONMENT NAME",
"region": "YOUR REGION NAME"
}'
Response
{
"status": true,
"message": "Environment is created successfully",
"environment": {
"id": 2,
"name": "development",
"region": "NORWAY-1",
"created_at": "2023-04-19T05:09:16"
}
}


Retrieve a list of environments

GET https://infrahub-api.nexgencloud.com/v1/core/environments

This endpoint retrieves a list of all your existing environments along with their respective details.


Parameters


No parameters.


Returns


Returns an array of environments objects, each providing details about an environment, including its name, ID, associated region, and creation date and time.


Attributes of the Environment object


status boolean

Indicates the success or failure of the operation. In this case, it is set to true, indicating that the environment has been created successfully.


message string

A message confirming the successful creation of the environment.


environments array

An array of objects each containing details about an environment.

Show child attributes
id integer

Unique identifier for the environment.


name string

Name of the environment.


region string

Name of the region associated with the environment.


created_at date-time

Date and time when the environment was created, presented in ISO 8601 format.

Example request
curl -X GET "https://infrahub-api.nexgencloud.com/v1/core/environments" \
-H "accept: application/json"\
-H "api_key: YOUR API KEY"
Response
{
"status": true,
"message": "Getting environments successful",
"environments": [
{
"name": "test",
"created_at": "2023-04-18T08:18:47",
"region": "NORWAY-1",
"id": 5
},
{...}
]
}


Change environment name

PUT https://infrahub-api.nexgencloud.com/v1/core/environments/{id}

This endpoint allows you to update the name of an environment. Specify the environment's ID in the path and include the desired name in the request body, as demonstrated below.


Path parameters


id REQUIRED integer

The ID of the environment for which the name is being changed.


Request body parameters


name REQUIRED string

The new name for the environment.


Returns


Returns the environment object, which contains details about the environment, including its new name. Otherwise an error has occurred.


Attributes of the Environment object


status boolean

Indicates the success or failure of the operation. In this case, it is set to true, indicating that the environment's name has been successfully changed.


message string

A message confirming the successful changing of the environment's name.


environments array

An object containing details about the environment.

Show child attributes
id integer

Unique identifier for the environment.


name string

The new name of the environment.


region string

Name of the region associated with the environment.


created_at date-time

Date and time when the environment was created, presented in ISO 8601 format.

Example request
curl -X PUT "https://infrahub-api.nexgencloud.com/v1/core/environments/{id}" \
-H "accept: application/json"\
-H "api_key: YOUR API KEY"
-d '{
"name": "example-env-edited"
}'

Response
{
"status": true,
"message": "Update an environment success",
"environment": {
"id": 45,
"region": "NORWAY-1",
"name": "example-env-edited",
"created_at": "2023-05-17T08:34:07"
}
}


Environment permissions

The following Role-Based Access Control system permissions can be applied to environments to manage user user resource access.

IDPermissionDescriptionAPI Endpoint
1environment:listGrants user permissions to view a list of environments.GET /core/environments
2environment:createGrants user permissions to create an environment.POST /core/environments
3environment:detailsGrants user permissions to view environment details.GET /core/environments/:env_id
4environment:updateGrants user permissions to update an environment.PUT /core/environments/:env_id
5environment:deleteGrants user permissions to delete an environmentDELETE /core/environments/:env_id

Back to top