Skip to content

Commit

Permalink
update docs to version 0.7.0 (#325)
Browse files Browse the repository at this point in the history
Co-authored-by: Pim Simons <[email protected]>
  • Loading branch information
pim-simons and pim-simons authored Aug 29, 2022
1 parent 36a72e7 commit 89bd4a3
Show file tree
Hide file tree
Showing 19 changed files with 2,314 additions and 0 deletions.
18 changes: 18 additions & 0 deletions docs/versioned_docs/version-v0.7.0/01-index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
---
title: "Arcus - Scripting"
layout: default
slug: /
sidebar_label: Welcome
---

# Introduction
Arcus Scripting provides an answer to many frequently-used, repeated tasks in Azure. Categorized in separate PowerShell modules, these functions help with backing up your API Management service, removing resource locks, disabling Logic Apps, injecting content in ARM templates, and many more!

Take a quick look at the sidebar categories to find more information on the resource or topic you're working with.

![Arcus Azure diagram](/img/arcus-azure-diagram.png)

# License
This is licensed under The MIT License (MIT). Which means that you can use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the web application. But you always need to state that Codit is the original author of this web application.

*[Full license here](https://github.com/arcus-azure/arcus.scripting/blob/master/LICENSE)*
84 changes: 84 additions & 0 deletions docs/versioned_docs/version-v0.7.0/02-Features/powershell/arm.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
---
title: "ARM templates"
layout: default
---

# ARM

This module provides the following capabilities:
- [ARM](#arm)
- [Installation](#installation)
- [Injecting content into an ARM template](#injecting-content-into-an-arm-template)
- [Usage](#usage)
- [Injection Instructions](#injection-instructions)
- [Recommendations](#recommendations)

## Installation

To have access to the following features, you have to import the module:

```powershell
PS> Install-Module -Name Arcus.Scripting.ARM
```

## Injecting content into an ARM template

In certain scenarios, you have to embed content into an ARM template to deploy it.

However, the downside of it is that it's buried inside the template and tooling around it might be less ideal - An example of this is OpenAPI specifications you'd want to deploy.

By using this script, you can inject external files inside your ARM template.

| Parameter | Mandatory | Description |
| --------- | --------- | ----------------------------------------------------------------------------------------------- |
| `Path` | no | The file path to the ARM template to inject the external files into (default: `$PSScriptRoot`) |

### Usage
Annotating content to inject:

```json
{
"type": "Microsoft.ApiManagement/service/apis",
"name": "[concat(parameters('ApiManagement.Name'),'/', parameters('ApiManagement.Api.Name'))]",
"apiVersion": "2019-01-01",
"properties": {
"subscriptionRequired": true,
"path": "demo",
"value": "${ FileToInject='.\\..\\openapi\\api-sample.json', InjectAsJsonObject}$",
"format": "swagger-json"
},
"tags": "[variables('Tags')]",
"dependsOn": [
]
}
```

Injecting the content:

```powershell
PS> Inject-ArmContent -Path deploy\arm-template.json
```

### Injection Instructions

It is possible to supply injection instructions in the injection annotation, this allows you to add specific functionality to the injection. These are the available injection instructions:

| Injection Instruction | Description |
| --------------------- | ----------------------------------------------------------------------------------------------------------- |
| `EscapeJson` | Replace double quotes not preceded by a backslash with escaped quotes |
| `ReplaceSpecialChars` | Replace newline characters with literal equivalents, tabs with spaces and `"` with `\"` |
| `InjectAsJsonObject` | Tests if the content is valid JSON and makes sure the content is injected without surrounding double quotes |

Usage of multiple injection instructions is supported as well, for example if you need both the `EscapeJson` and `ReplaceSpecialChars` functionality.
The reference to the file to inject can either be a path relative to the 'parent' file or an absolute path.

Some examples are:
```powershell
${ FileToInject = ".\Parent Directory\file.xml" }
${ FileToInject = "c:\Parent Directory\file.xml" }
${ FileToInject = ".\Parent Directory\file.xml", EscapeJson, ReplaceSpecialChars }
${ FileToInject = '.\Parent Directory\file.json', InjectAsJsonObject }
```

### Recommendations
Always inject the content in your ARM template as soon as possible, preferably during release build that creates the artifact
Loading

0 comments on commit 89bd4a3

Please sign in to comment.