Use Docker containers in disconnected environments

Artikkel
11/15/2023

Containers enable you to run Azure AI services APIs in your own environment, and are great for your specific security and data governance requirements. Disconnected containers enable you to use several of these APIs disconnected from the internet. Currently, the following containers can be run in this manner:

Before attempting to run a Docker container in an offline environment, make sure you know the steps to successfully download and use the container. For example:

Host computer requirements and recommendations.
The Docker pull command you'll use to download the container.
How to validate that a container is running.
How to send queries to the container's endpoint, once it's running.

Request access to use containers in disconnected environments

Fill out and submit the request form to request access to the containers disconnected from the internet.

The form requests information about you, your company, and the user scenario for which you'll use the container. After you submit the form, the Azure AI services team reviews it and emails you with a decision within 10 business days.

Important

On the form, you must use an email address associated with an Azure subscription ID.
The Azure resource you use to run the container must have been created with the approved Azure subscription ID.
Check your email (both inbox and junk folders) for updates on the status of your application from Microsoft.

After you're approved, you'll be able to run the container after you download it from the Microsoft Container Registry (MCR), described later in the article.

You won't be able to run the container if your Azure subscription hasn't been approved.

Access is limited to customers that meet the following requirements:

Your organization should be identified as strategic customer or partner with Microsoft.
Disconnected containers are expected to run fully offline, hence your use cases must meet one of below or similar requirements:
- Environment or device(s) with zero connectivity to internet.
- Remote location that occasionally has internet access.
- Organization under strict regulation of not sending any kind of data back to cloud.
Application completed as instructed - Please pay close attention to guidance provided throughout the application to ensure you provide all the necessary information required for approval.

Purchase a commitment tier pricing plan for disconnected containers

Create a new resource

Sign in to the Azure portal and select Create a new resource for one of the applicable Azure AI services listed above.
Enter the applicable information to create your resource. Be sure to select Commitment tier disconnected containers as your pricing tier.
Note
- You will only see the option to purchase a commitment tier if you have been approved by Microsoft.
- Pricing details are for example only.
Select Review + Create at the bottom of the page. Review the information, and select Create.

Configure container for disconnected usage

See the following documentation for steps on downloading and configuring the container for disconnected usage:

Speech service

Language service

Environment variable names in Kubernetes deployments

Some Azure AI Containers, for example Translator, require users to pass environmental variable names that include colons (:) when running the container. This will work fine when using Docker, but Kubernetes does not accept colons in environmental variable names. To resolve this, you can replace colons with double underscore characters (__) when deploying to Kubernetes. See the following example of an acceptable format for environment variable names:

        env:  
        - name: Mounts__License
          value: "/license"
        - name: Mounts__Output
          value: "/output"

This example replaces the default format for the Mounts:License and Mounts:Output environment variable names in the docker run command.

Container image and license updates

Container license files are used as keys to decrypt certain files within each container image. If these encrypted files happen to be updated within a new container image, the license file you have may fail to start the container even if it worked with the previous version of the container image. To avoid this issue, we recommend that you download a new license file from the resource endpoint for your container provided in Azure portal after you pull new image versions from mcr.microsoft.com.

To download a new license file, you can add DownloadLicense=True to your docker run command along with a license mount, your API Key, and your billing endpoint. Refer to your container's documentation for detailed instructions.

Usage records

When operating Docker containers in a disconnected environment, the container will write usage records to a volume where they're collected over time. You can also call a REST endpoint to generate a report about service usage.

Arguments for storing logs

When run in a disconnected environment, an output mount must be available to the container to store usage logs. For example, you would include -v /host/output:{OUTPUT_PATH} and Mounts:Output={OUTPUT_PATH} in the example below, replacing {OUTPUT_PATH} with the path where the logs will be stored:

docker run -v /host/output:{OUTPUT_PATH} ... <image> ... Mounts:Output={OUTPUT_PATH}

Get records using the container endpoints

The container provides two endpoints for returning records about its usage.

Get all records

The following endpoint will provide a report summarizing all of the usage collected in the mounted billing record directory.

https://<service>/records/usage-logs/

It will return JSON similar to the example below.

{
  "apiType": "noop",
  "serviceName": "noop",
  "meters": [
    {
      "name": "Sample.Meter",
      "quantity": 253
    }
  ]
}

Get records for a specific month

The following endpoint will provide a report summarizing usage over a specific month and year.

https://<service>/records/usage-logs/{MONTH}/{YEAR}

it will return a JSON response similar to the example below:

{
  "apiType": "string",
  "serviceName": "string",
  "meters": [
    {
      "name": "string",
      "quantity": 253
    }
  ]
}

Purchase a commitment plan to use containers in disconnected environments

Commitment plans for disconnected containers have a calendar year commitment period. When you purchase a plan, you'll be charged the full price immediately. During the commitment period, you can't change your commitment plan, however you can purchase additional unit(s) at a pro-rated price for the remaining days in the year. You have until midnight (UTC) on the last day of your commitment, to end a commitment plan.

You can choose a different commitment plan in the Commitment Tier pricing settings of your resource.

End a commitment plan

If you decide that you don't want to continue purchasing a commitment plan, you can set your resource's auto-renewal to Do not auto-renew. Your commitment plan will expire on the displayed commitment end date. After this date, you won't be charged for the commitment plan. You'll be able to continue using the Azure resource to make API calls, charged at pay-as-you-go pricing. You have until midnight (UTC) on the last day of the year to end a commitment plan for disconnected containers, and not be charged for the following year.

Troubleshooting

If you run the container with an output mount and logging enabled, the container generates log files that are helpful to troubleshoot issues that happen while starting or running the container.

Tip

For more troubleshooting information and guidance, see Disconnected containers Frequently asked questions (FAQ).

Next steps

Azure AI containers overview