In this document, we go over the deployFhirStarter.bash script for deploying Azure API for FHIR. We cover script execution and the steps for completing the install.
There are no open issues at this time.
The deployFhirStarter.bash script will gather (and export) information necessary for the proper deployment and configuration of Azure API for FHIR and associated Azure resources. Before going forward with the deploy process, please make sure the following requirements are met.
- User must have rights to deploy Azure resources at the Subscription scope (i.e., Contributor role).
Note: This script will prompt the user with the option to create a new Resource Group for Azure API for FHIR, and within the Resource Group, the user will have the option to deploy a new Key Vault. Alternatively, the script gives the option to input the name of an existing Resource Group, and the script also leaves the option to use an existing Key Vault instead of creating a new one. In either case (new or existing), the script needs to establish a Key Vault for securing Service Client Credentials used with Azure API for FHIR and FHIR-Proxy. If you opt to use an existing Resource Group and Key Vault, it is important that only one Key Vault be in the Resource Group where Azure API for FHIR is deployed. If multiple Key Vaults are in the Azure API for FHIR Resource Group, problems can arise later when deploying FHIR-Proxy and other Azure resources. If necessary, please use the backup and restore option to copy credentials for central storage in one Key Vault.
Note:
The deployFhirStarter.bash script is designed and tested for the Azure Cloud Shell - Bash Shell environment.
Note: For testing Azure API for FHIR after it is deployed, we assume users have access to the Postman API testing utility (desktop or web client). Please visit here for information on obtaining Postman. Instructions for setting up Postman to test Azure API for FHIR are available here.
All Azure resource types have a scope in which resource names must be unique. Some resource names, such as PaaS services with public endpoints, have global scopes. Therefore, their names must be unique across the entire Azure platform. Our deployment scripts suggest resource names in alignment with Azure best practices. Users are prompted to accept a default (automatically generated) resource name, or they have the option to supply their own custom resource name during installation. See below for an example of the default Azure API for FHIR resource naming convention used in the deployFhirStarter.bash script. Note that while the default Environment label is dev (for deploying in a development environment), the script also gives the option to select qa (for a quality assurance/test environment), or prod (for a production environment).
| Resource Type | Deploy App Name | Environment | Number | Resource Name Example (automatically generated) |
|---|---|---|---|---|
| api | fhir | dev | random | api-fhir-dev-12345 |
Azure Resources deployed with the deployFhirStarter.bash script are automatically tagged with their origin and deployment name (see example below). Users are able to add/change Tags after installation.
| Origin | Deployment |
|---|---|
| HealthArchitectures | FHIRStarter |
Launch Azure Cloud Shell (Bash Environment)
CTRL+click (Windows or Linux) or CMD+click (Mac) to open in a new tab.
Clone this repo in your Azure Cloud Shell environment.
git clone https://github.com/microsoft/fhir-starter.git
Change the working directory in your Azure Cloud Shell environment to the ./fhir-starter/scripts directory.
cd $HOME/fhir-starter/scripts
Make the Bash script inside the ./fhir-starter/scripts directory executable.
chmod +x *.bash
The deployFhirStarter.bash script is the main deployment script for Azure API for FHIR and associated components.
Ensure you are in the proper directory.
cd $HOME/fhir-starter/scripts
Launch the deployFhirStarter.bash shell script inside the fhir-starter/scripts directory.
./deployFhirStarter.bash
-
The script will take you through the deployment steps and prompt you directly in the Azure Cloud Shell interface for your input (where needed).
-
You will be prompted to accept the default values for the following parameters:
subscriptionId,resourceGroupName,resourceGroupLocation,keyVaultName,fhirServiceName. At each prompt, you will also have the option to enter a custom parameter value should you choose not to accept the default value.
Alternatively, the deployFhirStarter.bash script can launch with command line options. You can pre-specify the <value> for any of the supported parameters (see below).
./deployFhirStarter.bash -i <subscriptionId> -g <resourceGroupName> -l <resourceGroupLocation> -k <keyVaultName> -n <fhirServiceName> -p <yes -or - no for postman setup>
Azure Components installed
- Resource Group (if needed - see the Prerequisites section above if you choose to opt out of creating a new Resource Group)
- Azure API for FHIR
- Key Vault (customers can choose to use an existing Key Vault as long as the Key Vault's Purge Protection is disabled - see the Prerequisites section above for more info)
- Azure AD Application Service Principal for use with FHIR-Proxy Authentication and RBAC (use the
deployfhirproxy.bashscript available here to deploy FHIR-Proxy after running thedeployFhirStarter.bashscript)
Information generated by this script (if not customized by user)
(see the Naming & Tagging section above about default naming conventions)
- Azure API for FHIR Resource Name
- Key Vault Name
- Resource Group Location
- Resource Group Name
Key Vault values saved by this script ("FS" stands for "FHIR Server")
| Name | Value | Use |
|---|---|---|
| FS-TENANT-NAME | Azure AD Tenant GUID | Tenant where Client applications can obtain a Token |
| FS-CLIENT-ID | Service Client Application ID | Client Application ID used for Token Access |
| FS-CLIENT-SECRET | Service Client Application Secret | Client Application Secret used for Token Access |
| FS-SECRET | Service Client Application Secret | Saved for backwards compatibility |
| FS-RESOURCE | Application Endpoint for Auth Access | Endpoint for Authority (AD) Token grant |
| FS-URL | Application Endpoint for Clients | Endpoint for FHIR Service interaction |
Once the deployFhirStarter.bash script finishes deployment, customers can use Postman to test access to the new Azure API for FHIR instance. Instructions on setting up Postman can be found in the fhir-starter/docs directory here.
