| title | description | services | keywords | author | ms.author | ms.date | ms.topic | ms.service | ms.custom | ms.devlang | manager |
|---|---|---|---|---|---|---|---|---|---|---|---|
Create a function on Linux using a custom image (preview) | Microsoft Docs |
Learn how to create Azure Functions running on a custom Linux image. |
functions |
ggailey777 |
glenga |
10/19/2018 |
tutorial |
azure-functions |
mvc |
azure-cli |
jeconnoc |
Azure Functions lets you host your functions on Linux in your own custom container. You can also host on a default Azure App Service container. This functionality is currently in preview and requires the Functions 2.0 runtime.
In this tutorial, you learn how to deploy your functions to Azure as a custom Docker image. This pattern is useful when you need to customize the built-in App Service container image. You may want to use a custom image when your functions need a specific language version or require a specific dependency or configuration that isn't provided within the built-in image.
This tutorial walks you through how to use Azure Functions Core Tools to create a function in a custom Linux image. You publish this image to a function app in Azure, which was created using the Azure CLI.
In this tutorial, you learn how to:
[!div class="checklist"]
- Create a function app and Dockerfile using Core Tools.
- Build a custom image using Docker.
- Publish a custom image to a container registry.
- Create an Azure Storage account.
- Create a Linux App Service plan.
- Deploy a function app from Docker Hub.
- Add application settings to the function app.
The following steps are supported on a Mac, Windows, or Linux computer.
Before running this sample, you must have the following:
-
Install Azure Core Tools version 2.x.
-
Install the Azure CLI. This article requires the Azure CLI version 2.0 or later. Run
az --versionto find the version you have.
You can also use the Azure Cloud Shell. -
An active Azure subscription.
[!INCLUDE quickstarts-free-trial-note]
Run the following command from the command line to create a function app project in the MyFunctionProj folder of the current local directory.
func init MyFunctionProj --dockerWhen you include the --docker option, a dockerfile is generated for the project. This file is used to create a custom container in which to run the project. The base image used depends on the worker runtime language chosen.
When prompted, choose a worker runtime from the following languages:
dotnet: creates a .NET class library project (.csproj).node: creates a JavaScript project.
When the command executes, you see something like the following output:
Writing .gitignore
Writing host.json
Writing local.settings.json
Writing Dockerfile
Use the following command to navigate to the new MyFunctionProj project folder.
cd MyFunctionProj[!INCLUDE functions-create-function-core-tools]
[!INCLUDE functions-update-function-code]
[!INCLUDE functions-run-function-test-local]
Take a look at the Dockerfile in the root folder of the project. This file describes the environment that is required to run the function app on Linux. The following example is a Dockerfile that creates a container that runs a function app on the JavaScript (Node.js) worker runtime:
FROM mcr.microsoft.com/azure-functions/node:2.0
ENV AzureWebJobsScriptRoot=/home/site/wwwroot
COPY . /home/site/wwwroot
Note
When hosting an image in a private container registry, you should add the connection settings to the function app by using ENV variables in the Dockerfile. Because this tutorial cannot guarantee that you use a private registry, the connection settings are added after the deployment by using the Azure CLI as a security best practice.
In the root folder, run the docker build command, and provide a name, mydockerimage, and tag, v1.0.0. Replace <docker-id> with your Docker Hub account ID. This command builds the Docker image for the container.
docker build --tag <docker-id>/mydockerimage:v1.0.0 .When the command executes, you see something like the following output, which in this case is for a JavaScript worker runtime:
Sending build context to Docker daemon 17.41kB
Step 1/3 : FROM mcr.microsoft.com/azure-functions/node:2.0
2.0: Pulling from azure-functions/node
802b00ed6f79: Pull complete
44580ea7a636: Pull complete
73eebe8d57f9: Pull complete
3d82a67477c2: Pull complete
8bd51cd50290: Pull complete
7bd755353966: Pull complete
Digest: sha256:480e969821e9befe7c61dda353f63298f2c4b109e13032df5518e92540ea1d08
Status: Downloaded newer image for mcr.microsoft.com/azure-functions/node:2.0
---> 7c71671b838f
Step 2/3 : ENV AzureWebJobsScriptRoot=/home/site/wwwroot
---> Running in ed1e5809f0b7
Removing intermediate container ed1e5809f0b7
---> 39d9c341368a
Step 3/3 : COPY . /home/site/wwwroot
---> 5e196215935a
Successfully built 5e196215935a
Successfully tagged <docker-id>/mydockerimage:v1.0.0Verify that the image you built works by running the Docker image in a local container. Issue the docker run command and pass the name and tag of the image to it. Be sure to specify the port using the -p argument.
docker run -p 8080:80 -it <docker-ID>/mydockerimage:v1.0.0With the custom image running in a local Docker container, verify the function app and container are functioning correctly by browsing to http://localhost:8080.
You can optionally test your function again, this time in the local container using the following URL:
http://localhost:8080/api/myhttptrigger?name=<yourname>
After you have verified the function app in the container, stop the execution. Now, you can push the custom image to your Docker Hub account.
A registry is an application that hosts images and provides services image and container services. To share your image, you must push it to a registry. Docker Hub is a registry for Docker images that allows you to host your own repositories, either public or private.
Before you can push an image, you must sign in to Docker Hub using the docker login command. Replace <docker-id> with your account name and type in your password into the console at the prompt. For other Docker Hub password options, see the docker login command documentation.
docker login --username <docker-id>A "login succeeded" message confirms that you are logged in. After you have signed in, you push the image to Docker Hub by using the docker push command.
docker push <docker-id>/mydockerimage:v1.0.0Verify that the push succeeded by examining the command's output.
The push refers to a repository [docker.io/<docker-id>/mydockerimage:v1.0.0]
24d81eb139bf: Pushed
fd9e998161c9: Mounted from <docker-id>/mydockerimage
e7796c35add2: Mounted from <docker-id>/mydockerimage
ae9a05b85848: Mounted from <docker-id>/mydockerimage
45c86e20670d: Mounted from <docker-id>/mydockerimage
v1.0.0: digest: sha256:be080d80770df71234eb893fbe4d... size: 1796Now, you can use this image as the deployment source for a new function app in Azure.
[!INCLUDE functions-create-resource-group]
[!INCLUDE functions-create-storage-account]
Linux hosting for Functions is currently not supported on consumption plans. You have to host Linux container apps in a Linux App Service plan. To learn more about hosting, see Azure Functions hosting plans comparison.
[!INCLUDE app-service-plan-no-h]
The function app hosts the execution of your functions. Create a function app from a Docker Hub image by using the az functionapp create command.
In the following command, substitute a unique function app name where you see the <app_name> placeholder and the storage account name for <storage_name>. The <app_name> is used as the default DNS domain for the function app, and so the name needs to be unique across all apps in Azure. As before, <docker-id> is your Docker account name.
az functionapp create --name <app_name> --storage-account <storage_name> --resource-group myResourceGroup \
--plan myAppServicePlan --deployment-container-image-name <docker-id>/mydockerimage:v1.0.0
After the function app has been created, the Azure CLI shows information similar to the following example:
{
"availabilityState": "Normal",
"clientAffinityEnabled": true,
"clientCertEnabled": false,
"containerSize": 1536,
"dailyMemoryTimeQuota": 0,
"defaultHostName": "quickstart.azurewebsites.net",
"enabled": true,
"enabledHostNames": [
"quickstart.azurewebsites.net",
"quickstart.scm.azurewebsites.net"
],
....
// Remaining output has been truncated for readability.
}The deployment-container-image-name parameter indicates the image hosted on Docker Hub to use to create the function app.
The function needs the connection string to connect to the default storage account. When you are publishing your custom image to a private container account, you should instead set these application settings as environment variables in the Dockerfile using the ENV instruction, or something similar.
In this case, <storage_account> is the name of the storage account you created. Get the connection string with the az storage account show-connection-string command. Add these application settings in the function app with the az functionapp config appsettings set command.
storageConnectionString=$(az storage account show-connection-string \
--resource-group myResourceGroup --name <storage_account> \
--query connectionString --output tsv)
az functionapp config appsettings set --name <function_app> \
--resource-group myResourceGroup \
--settings AzureWebJobsDashboard=$storageConnectionString \
AzureWebJobsStorage=$storageConnectionString
Note
If your container is private, you would have to set the following application settings as well
- DOCKER_REGISTRY_SERVER_USERNAME
- DOCKER_REGISTRY_SERVER_PASSWORD
You will have to stop and then start your function app for these values to be picked up
You can now test your functions running on Linux in Azure.
[!INCLUDE functions-test-function-code]
[!INCLUDE functions-cleanup-resources]
In this tutorial, you learned how to:
[!div class="checklist"]
- Create a function app and Dockerfile using Core Tools.
- Build a custom image using Docker.
- Publish a custom image to a container registry.
- Create an Azure Storage account.
- Create a Linux App Service plan.
- Deploy a function app from Docker Hub.
- Add application settings to the function app.
Learn how to enable continuous integration functionality built into the core App Service platform. You can configure your function app so that the container is redeployed when you update your image in Docker Hub.
[!div class="nextstepaction"] Continuous deployment with Web App for Containers