Skip to main content

Getting started

Bicep extensions let you manage resources that are not Azure Resource Manager resources — GitHub repositories, Kubernetes objects, Helm releases, and so on — using the same declarative language you already use for Azure.

Every extension in this catalogue is a local extension: a self-contained binary that Bicep starts on your machine during a deployment, and communicates with over gRPC.

Prerequisites​

  • The Bicep CLI (or the Azure CLI, which bundles it).
  • Any credentials the extension itself needs, such as a kubeconfig file or a GitHub token. These are described on each extension's page.

1. Enable local deployment​

Local extensions are behind experimental feature flags. Create a bicepconfig.json next to your Bicep file:

{
  "experimentalFeaturesEnabled": {
    "localDeploy": true,
    "ociEnabled": true
  },
  "implicitExtensions": []
}

localDeploy enables local deployments, and ociEnabled allows extensions to be restored from an OCI registry.

Setting implicitExtensions to an empty array disables the az extension, which Bicep includes by default. Leave it out if you also want to declare Azure resources in the same file.

2. Register the extension​

Add the extension to the extensions section of the same file, pointing at the OCI artifact and version shown on the extension's page:

{
  "experimentalFeaturesEnabled": {
    "localDeploy": true,
    "ociEnabled": true
  },
  "implicitExtensions": [],
  "extensions": {
    "github": "br:ghcr.io/anthony-c-martin/bicep-ext-github:0.0.1"
  }
}

The key (github above) is the alias you use in your Bicep file. Pinning an explicit version is recommended so deployments stay reproducible.

3. Declare resources​

Reference the extension with an extension statement, then declare resources using the types it exposes:

targetScope = 'local'

extension github

resource repo 'Repository' = {
  owner: 'contoso'
  name: 'hello-world'
  description: 'Created with Bicep'
  visibility: 'Public'
}

output repositoryUrl string = repo.htmlUrl

Some extensions need configuration, which is supplied with a with clause:

extension kubernetes with {
  kubeConfig: loadTextContent('~/.kube/config')
  namespace: 'default'
}

The available configuration properties are listed under Configuration on each extension's page.

4. Deploy​

Local deployments use the bicep local-deploy command, which takes a .bicepparam file:

main.bicepparam
using 'main.bicep'
bicep local-deploy main.bicepparam

Bicep downloads the extension binary, starts it, and calls it to create or update each resource.

Where types come from​

The reference pages in this catalogue are generated by downloading each extension's published artifact, starting the binary, and calling the GetTypeFiles gRPC method defined in extension.proto. The documentation therefore reflects exactly what the extension reports about itself.

Next steps​

Further reading​