Create your first function on Azure Arc (preview)

In this quickstart, you create an Azure Functions project and deploy it to a function app running on an Azure Arc-enabled Kubernetes cluster. To learn more, see App Service, Functions, and Logic Apps on Azure Arc. This scenario only supports function apps running on Linux.

Note

Support for running functions on an Azure Arc-enabled Kubernetes cluster is currently in preview.

Publishing PowerShell function projects to Azure Arc-enabled Kubernetes clusters isn't currently supported. If you need to deploy PowerShell functions to Azure Arc-enabled Kubernetes clusters, create your function app in a container.

Prerequisites

On your local computer:

Create an App Service Kubernetes environment

Before you begin, you must create an App Service Kubernetes environment for an Azure Arc-enabled Kubernetes cluster.

Note

When you create the environment, make sure to make note of both the custom location name and the name of the resource group that contains the custom location. You can use these to find the custom location ID, which you'll need when creating your function app in the environment.

If you didn't create the environment, check with your cluster administrator.

Add Azure CLI extensions

Launch the Bash environment in Azure Cloud Shell.

Launch Cloud Shell in a new window

Because these CLI commands are not yet part of the core CLI set, add them with the following commands:

az extension add --upgrade --yes --name customlocation
az extension remove --name appservice-kube
az extension add --yes --source "https://aka.ms/appsvc/appservice_kube-latest-py2.py3-none-any.whl"

Create the local function project

In Azure Functions, a function project is the unit of deployment and execution for one or more individual functions that each responds to a specific trigger. All functions in a project share the same local and hosting configurations. In this section, you create a function project that contains a single function.

  1. Run the func init command, as follows, to create a functions project in a folder named LocalFunctionProj with the specified runtime:

    func init LocalFunctionProj --dotnet
    
  2. Navigate into the project folder:

    cd LocalFunctionProj
    

    This folder contains various files for the project, including configurations files named local.settings.json and host.json. By default, the local.settings.json file is excluded from source control in the .gitignore file. This exclusion is because the file can contain secrets that are downloaded from Azure.

  3. Add a function to your project by using the following command, where the --name argument is the unique name of your function (HttpExample) and the --template argument specifies the function's trigger (HTTP).

    func new --name HttpExample --template "HTTP trigger" --authlevel "anonymous"
    

Run the function locally

  1. Run your function by starting the local Azure Functions runtime host from the LocalFunctionProj folder:

    func start
    

    Toward the end of the output, the following lines should appear:

     ...
    
     Now listening on: http://0.0.0.0:7071
     Application started. Press Ctrl+C to shut down.
    
     Http Functions:
    
             HttpExample: [GET,POST] http://localhost:7071/api/HttpExample
     ...
    
     

    Note

    If HttpExample doesn't appear as shown above, you likely started the host from outside the root folder of the project. In that case, use Ctrl+C to stop the host, navigate to the project's root folder, and run the previous command again.

  2. Copy the URL of your HttpExample function from this output to a browser and append the query string ?name=<YOUR_NAME>, making the full URL like http://localhost:7071/api/HttpExample?name=Functions. The browser should display a response message that echoes back your query string value. The terminal in which you started your project also shows log output as you make requests.

  3. When you're done, use Ctrl+C and choose y to stop the functions host.

Get the custom location

To be able to create a function app in a custom location, you'll need to get information about the environment.

Get the following information about the custom location from your cluster administrator (see Create a custom location).

customLocationGroup="<resource-group-containing-custom-location>"
customLocationName="<name-of-custom-location>"

Get the custom location ID for the next step.

customLocationId=$(az customlocation show \
    --resource-group $customLocationGroup \
    --name $customLocationName \
    --query id \
    --output tsv)

Create Azure resources

Before you can deploy your function code to your new App Service Kubernetes environment, you need to create two more resources:

  • A Storage account, which is currently required by tooling and isn't part of the environment.
  • A function app, which provides the context for executing your function code. The function app runs in the App Service Kubernetes environment and maps to your local function project. A function app lets you group functions as a logical unit for easier management, deployment, and sharing of resources.

Note

Function apps run in an App Service Kubernetes environment on a Dedicated (App Service) plan. When you create your function app without an existing plan, the correct plan is created for you.

Create Storage account

Use the az storage account create command to create a general-purpose storage account in your resource group and region:

az storage account create --name <STORAGE_NAME> --location westeurope --resource-group myResourceGroup --sku Standard_LRS

Note

A storage account is currently required by Azure Functions tooling.

In the previous example, replace <STORAGE_NAME> with a name that is appropriate to you and unique in Azure Storage. Names must contain three to 24 characters numbers and lowercase letters only. Standard_LRS specifies a general-purpose account, which is supported by Functions. The --location value is a standard Azure region.

Create the function app

Run the az functionapp create command to create a new function app in the environment.

az functionapp create --resource-group MyResourceGroup --name <APP_NAME> --custom-location <CUSTOM_LOCATION_ID> --storage-account <STORAGE_NAME> --functions-version 3 --runtime dotnet 

In this example, replace <CUSTOM_LOCATION_ID> with the ID of the custom location you determined for the App Service Kubernetes environment. Also, replace <STORAGE_NAME> with the name of the account you used in the previous step, and replace <APP_NAME> with a globally unique name appropriate to you.

Deploy the function project to Azure

After you've successfully created your function app in Azure, you're now ready to deploy your local functions project by using the func azure functionapp publish command.

In the following example, replace <APP_NAME> with the name of your app.

func azure functionapp publish <APP_NAME>

The publish command shows results similar to the following output (truncated for simplicity):

...

Getting site publishing info...
Creating archive for current directory...
Performing remote build for functions project.

...

Deployment successful.
Remote build succeeded!
Syncing triggers...
Functions in msdocs-azurefunctions-qs:
    HttpExample - [httpTrigger]
        Invoke url: https://msdocs-azurefunctions-qs.azurewebsites.net/api/httpexample

Because it can take some time for a full deployment to complete on an Azure Arc-enabled Kubernetes cluster, you may want to re-run the following command to verify your published functions:

func azure functionapp list-functions

Invoke the function on Azure

Because your function uses an HTTP trigger, you invoke it by making an HTTP request to its URL in the browser or with a tool like curl.

Copy the complete Invoke URL shown in the output of the publish command into a browser address bar, appending the query parameter &name=Functions. The browser should display similar output as when you ran the function locally.

The output of the function run on Azure in a browser

Next steps

Now that you have your function app running in a container an Azure Arc-enabled App Service Kubernetes environment, you can connect it to Azure Storage by adding a Queue Storage output binding.