azure-developer-devcenter 1.0.0

Description:

azuredeveloperdevcenter 1.0.0

Azure DevCenter Service client library for Python
The Azure DevCenter package provides access to manage resources for Microsoft Dev Box and Azure Deployment Environments. This SDK enables managing developer machines and environments in Azure.
Use the package for Azure DevCenter to:

Create, access, manage, and delete Dev Box resources
Create, deploy, manage, and delete Environment resources

Getting started
Installing the package
python -m pip install azure-developer-devcenter

Prerequisites

Python 3.7 or later is required to use this package.
You need an Azure subscription to use this package.
For Dev Box operations you must have configured a DevCenter, Project, Network Connection, Dev Box Definition, and Pool.
For Deployment Environments operations you must have configured a DevCenter, Project, Catalog, Environment Definition and Environment Type.

Create Client with an Azure Active Directory Credential
In order to interact with the Dev Center service, you will need to create an instance of a client. An endpoint and credential are necessary to instantiate the client object.
For the endpoint use the Dev Center URI. It should have the format https://{tenantId}-{devCenterName}.{devCenterRegion}.devcenter.azure.com.
For the credential use an Azure Active Directory (AAD) token credential, providing an instance of the desired credential type obtained from the azure-identity library.
To authenticate with AAD, you must first install azure-identity using pip
pip install azure-identity

After setup, you can choose which type of credential from azure.identity to use.
As an example, DefaultAzureCredential can be used to authenticate the client:
Set the values of the client ID, tenant ID, and client secret of the AAD application as environment variables:
AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET
Use the returned token credential to authenticate the client.

import os

from azure.developer.devcenter import DevCenterClient
from azure.identity import DefaultAzureCredential

# Set the values of the dev center endpoint, client ID, and client secret of the AAD application as environment variables:
# DEVCENTER_ENDPOINT, AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET
try:
endpoint = os.environ["DEVCENTER_ENDPOINT"]
except KeyError:
raise ValueError("Missing environment variable 'DEVCENTER_ENDPOINT' - please set it before running the example")

# Build a client through AAD
client = DevCenterClient(endpoint, credential=DefaultAzureCredential())


With DevCenterClient you can execute operations in Dev Center, Dev Box and Environments REST operations group.
Examples

Create, Connect and Delete a Dev Box
Deploy and Delete an Environment

Create, Connect and Delete a Dev Box

import os

from azure.developer.devcenter import DevCenterClient
from azure.identity import DefaultAzureCredential

# Set the values of the dev center endpoint, client ID, and client secret of the AAD application as environment variables:
# DEVCENTER_ENDPOINT, AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET
try:
endpoint = os.environ["DEVCENTER_ENDPOINT"]
except KeyError:
raise ValueError("Missing environment variable 'DEVCENTER_ENDPOINT' - please set it before running the example")

# Build a client through AAD
client = DevCenterClient(endpoint, credential=DefaultAzureCredential())

# List available Projects
projects = client.list_projects()
if projects:
print("\nList of projects: ")
for project in projects:
print(f"{project.name}")

# Select first project in the list
target_project_name = list(projects)[0].name
else:
raise ValueError("Missing Project - please create one before running the example")

# List available Pools
pools = client.list_pools(target_pool_name)
if pools:
print("\nList of pools: ")
for pool in pools:
print(f"{pool.name}")

# Select first pool in the list
target_pool_name = list(pools)[0].name
else:
raise ValueError("Missing Pool - please create one before running the example")

# Stand up a new Dev Box
print(f"\nStarting to create dev box in project {target_project_name} and pool {target_pool_name}")

dev_box_poller = client.begin_create_dev_box(
target_project_name, "me", "Test_DevBox", {"poolName": target_pool_name}
)
dev_box = dev_box_poller.result()
print(f"Provisioned dev box with status {dev_box.provisioning_state}.")

# Connect to the provisioned Dev Box
remote_connection = client.get_remote_connection(target_project_name, "me", dev_box.name)
print(f"Connect to the dev box using web URL {remote_connection.web_url}")

# Tear down the Dev Box when finished
print(f"Starting to delete dev box.")

delete_poller = client.begin_delete_dev_box(target_project_name, "me", "Test_DevBox")
delete_result = delete_poller.result()
print(f"Completed deletion for the dev box with status {delete_result.status}")


Deploy and Delete an Environment

import os

from azure.developer.devcenter import DevCenterClient
from azure.identity import DefaultAzureCredential

# Set the values of the dev center endpoint, client ID, and client secret of the AAD application as environment variables:
# DEVCENTER_ENDPOINT, AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET
try:
endpoint = os.environ["DEVCENTER_ENDPOINT"]
except KeyError:
raise ValueError("Missing environment variable 'DEVCENTER_ENDPOINT' - please set it before running the example")

# Build a client through AAD
client = DevCenterClient(endpoint, credential=DefaultAzureCredential())

# List available Projects
projects = client.list_projects()
if projects:
print("\nList of projects: ")
for project in projects:
print(f"{project.name}")

# Select first project in the list
target_project_name = list(projects)[0].name
else:
raise ValueError("Missing Project - please create one before running the example")

# List available Catalogs
catalogs = client.list_catalogs(target_project_name)
if catalogs:
print("\nList of catalogs: ")
for catalog in catalogs:
print(f"{catalog.name}")

# Select first catalog in the list
target_catalog_name = list(catalogs)[0].name
else:
raise ValueError("Missing Catalog - please create one before running the example")

# List available Environment Definitions
environment_definitions = client.list_environment_definitions_by_catalog(target_project_name, target_catalog_name)
if environment_definitions:
print("\nList of environment definitions: ")
for environment_definition in environment_definitions:
print(f"{environment_definition.name}")

# Select first environment definition in the list
target_environment_definition_name = list(environment_definitions)[0].name
else:
raise ValueError("Missing Environment Definition - please create one before running the example")

# List available Environment Types
environment_types = client.list_environment_types(target_project_name)
if environment_types:
print("\nList of environment types: ")
for environment_type in environment_types:
print(f"{environment_type.name}")

# Select first environment type in the list
target_environment_type_name = list(environment_types)[0].name
else:
raise ValueError("Missing Environment Type - please create one before running the example")

print(
f"\nStarting to create environment in project {target_project_name} with catalog {target_catalog_name}, environment definition {target_environment_definition_name}, and environment type {target_environment_type_name}."
)

# Stand up a new environment
environment_name = "MyDevEnv"
environment = {
"environmentType": target_environment_type_name,
"catalogName": target_catalog_name,
"environmentDefinitionName": target_environment_definition_name,
}

environment_poller = client.begin_create_or_update_environment(
target_project_name, "me", environment_name, environment
)
environment_result = environment_poller.result()
print(f"Provisioned environment with status {environment_result.provisioning_state}.")

# Tear down the environment when finished
print(f"Starting to delete environment.")
delete_poller = client.begin_delete_environment(target_project_name, "me", environment_name)
delete_result = delete_poller.result()
print(f"Completed deletion for the environment with status {delete_result.status}")


Key concepts
Dev Boxes refer to managed developer machines running in Azure. Dev Boxes are provisioned in Pools, which define the network and image used for a Dev Box.
Environments refer to templated developer environments, which combine a template (Catalog Item) and parameters.
Troubleshooting
Errors can occur during initial requests and long-running operations, and will provide information about how to resolve the error.
Be sure to confirm that dependent resources, such as pools and catalogs, are set up properly and are in a healthy state. You will not be able to create resources with the package when your dependent resources are in a failed state.
Next steps
Get started by exploring our samples and starting to use the package!
Contributing
This project welcomes contributions and suggestions. Most contributions require
you to agree to a Contributor License Agreement (CLA) declaring that you have
the right to, and actually do, grant us the rights to use your contribution.
For details, visit https://cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether
you need to provide a CLA and decorate the PR appropriately (e.g., label,
comment). Simply follow the instructions provided by the bot. You will only
need to do this once across all repos using our CLA.
This project has adopted the
Microsoft Open Source Code of Conduct. For more information,
see the Code of Conduct FAQ or contact [email protected] with any
additional questions or comments.