Introduction

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

Explanation of the Add 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

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

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