Introduction

The ipm add command facilitates adding new packages to the local workspace and also directly downloads it from our remote servers.

Adding Multiple Packages

IPM now supports adding multiple packages at once using the --packages parameter. This approach streamlines the workspace setup process by reducing the number of commands needed.

ipm add --packages avm-bicep/virtual-machines avm-bicep/virtual-networks

This single command will download both packages to your workspace simultaneously. All packages added this way will:

  • Use the same working folder
  • Use the same download strategy
  • Download the latest available version of each package

To specify a working folder for all packages:

ipm add --packages avm-bicep/virtual-machines avm-bicep/virtual-networks --folder infrastructure

To apply a specific download strategy to all packages:

ipm add --packages avm-bicep/virtual-machines avm-bicep/virtual-networks --strategy multiple

Explanation of the Download Strategy

IPM supports two ways of adding packages. In most cases, the default option (simple) is the right choice. However, depending on your project’s needs, our “Multiple” strategy can be beneficial.

Single Strategy

The single strategy is the default approach for adding (downloading) new packages to your project. If you do not specify another working folder, you can only have one instance of a given package in a project.

In the example below, we add two packages with default settings. As you can see, the downloaded packages are directly placed in the packages directory: virtual-machines and virtual-networks.

ipm add -p avm-bicep/virtual-machines
ipm add -p avm-bicep/virtual-networks

Directory structure:

.
├── ipmhub.json
`── packages
    ├── virtual-machines   <---- First Package
    │   ├── extension
    │   │   ├── main.bicep
    │   │   `── README.md
    │   ├── modules
    │   │   ├── nic-configuration.bicep
    │   │   `── protected-item.bicep
    │   ├── packages
    │   │   ├── network-interface
    │   │   │   ├── DISCLAIMER.md
    │   │   │   ├── LICENSE.txt
    │   │   │   ├── main.bicep
    │   │   │   `── README.md
    │   │   `── public-ip-address
    │   │       ├── DISCLAIMER.md
    │   │       ├── LICENSE.txt
    │   │       ├── main.bicep
    │   │       `── README.md
    │   ├── DISCLAIMER.bicep
    │   ├── ipmhub.json
    │   ├── LICENSE.txt
    │   ├── main.bicep
    │   `── README.md
    `── virtual-networks  <---- Second package
        ├── packages
        │   ├── utl-common-types
        │   │   ├── DISCLAIMER.md
        │   │   ├── LICENSE.txt
        │   │   ├── main.bicep
        │   │   `── README.md
        ├── subnet
        │   ├── main.bicep
        │   `── README.md
        ├── virtual-network-peering
        │   ├── main.bicep
        │   `── README.md
        ├── DISCLAIMER.bicep
        ├── ipmhub.json
        ├── LICENSE.txt
        ├── main.bicep
        `── README.md

Multiple strategy

In the example below, we demonstrate adding two versions of the same package (underctrl/aks-quickstart). As depicted, each version is stored in its corresponding directory.

ipm add -p underctrl/aks-quickstart -v 0.0.5 -s multiple
ipm add -p underctrl/aks-quickstart -v 1.0.0 -s multiple

Directory structure: 

.
|-- ipmhub.json
`-- packages
    `-- aks-quickstart          <---- Package directory
        |-- 0.0.5               <---- Version 0.0.5
        |   |-- acr.bicep
        |   |-- aks.bicep
        |   |-- bicepconfig.json
        |   |-- ipmhub.json
        |   |-- keyvault.bicep
        |   |-- law.bicep
        |   |-- packages
        |   |   `-- nsg-package
        |   |       `-- main.bicep
        |   |-- pip.bicep
        |   |-- resource-groups.bicep
        |   |-- sharedConfig.json
        |   `-- vnet.bicep
        `-- 1.0.0           <---- Version 1.0.0
            |-- acr.bicep
            |-- aks.bicep
            |-- bicepconfig.json
            |-- example
            |   |-- main.bicep
            |   |-- pipelines
            |   |   |-- deploy-aks-resources.yml
            |   |   |-- deploy-resouregroups.yml
            |   |   `-- templates
            |   |       |-- create_artifact.yml
            |   |       |-- job-deploy.yml
            |   |       `-- job-whatif.yml
            |   |-- resource-groups.bicep
            |   `-- sharedConfig.json
            |-- keyvault.bicep
            |-- law.bicep
            |-- pip.bicep
            |-- resource-groups.bicep
            |-- sharedConfig.json
            `-- vnet.bicep

You can also combine multiple strategy with the multiple packages parameter:

ipm add --packages underctrl/aks-quickstart underctrl/aks-monitoring --strategy multiple

This would set up both packages using the multiple strategy in your workspace.

working folders

All packages are stored in a designated working folder. A project can accommodate multiple working directories, with the default directory being set to packages after executing ipm init.

In the following example, we add the same package with the same version. The initial command utilizes the default working folder, while the subsequent command directs the client to add the package to an alternative working folder.

ipm add -p avm-bicep/virtual-machines
ipm add -p avm-bicep/virtual-machines -f modules

Directory structure: 

.
|-- ipmhub.json
|-- modules         <---- alternative working folder
│   `── virtual-machines   <---- First Package
│       ├── extension
│       │   ├── main.bicep
│       │   `── README.md
│       ├── modules
│       │   ├── nic-configuration.bicep
│       │   `── protected-item.bicep
│       ├── packages
│       │   ├── network-interface
│       │   │   ├── DISCLAIMER.md
│       │   │   ├── LICENSE.txt
│       │   │   ├── main.bicep
│       │   │   `── README.md
│       │   `── public-ip-address
│       │       ├── DISCLAIMER.md
│       │       ├── LICENSE.txt
│       │       ├── main.bicep
│       │       `── README.md
│       ├── DISCLAIMER.bicep
│       ├── ipmhub.json
│       ├── LICENSE.txt
│       ├── main.bicep
│       `── README.md
`-- packages        <---- default working folder
    `── virtual-machines   <---- First Package
        ├── extension
        │   ├── main.bicep
        │   `── README.md
        ├── modules
        │   ├── nic-configuration.bicep
        │   `── protected-item.bicep
        ├── packages
        │   ├── network-interface
        │   │   ├── DISCLAIMER.md
        │   │   ├── LICENSE.txt
        │   │   ├── main.bicep
        │   │   `── README.md
        │   `── public-ip-address
        │       ├── DISCLAIMER.md
        │       ├── LICENSE.txt
        │       ├── main.bicep
        │       `── README.md
        ├── DISCLAIMER.bicep
        ├── ipmhub.json
        ├── LICENSE.txt
        ├── main.bicep
        `── README.md

You can also apply a different working folder to multiple packages at once:

ipm add --packages avm-bicep/virtual-machines avm-bicep/virtual-networks --folder infrastructure

This places all specified packages into the “infrastructure” folder.

Change default working folder

It’s also possible to change the default working folder so that all packages are downloaded to an alternative folder without specifying it each time. Changing the default working folder is a workspace-specific setting and can be modified in the ipmhub.json file.

{
  "workingFolder": "ALTERNATIVE_PATH_HERE",  
  "packages": []
}

Naming rules

By default, when you add a package using ipm add, the folder’s name in which the package is downloaded only contains the package name. If you want to include the publisher’s name as well, you can use the parameter -n or -namingrule.

ipm add -p avm-bicep/virtual-machine-scale-sets -n full

This results in:

.
|── ipmhub.json
`── packages
    `── [avm-bicep]virtual-machine-scale-sets <---- See the Publisher name here
        |── extension
        |   |── main.bicep
        |   `── README.md
        |── DISCLAIMER.md
        |── LICENSE.txt
        |── main.bicep
        `── README.md

The naming rule also applies when using multiple packages:

ipm add --packages avm-bicep/virtual-machines avm-bicep/virtual-networks -n full

This applies the full naming rule to all packages downloaded by the command.