haufe-azure-arm-utils/README.md

Azure ARM Node Utilities

# haufe-azure-arm-utils

This is a collection of tools/Azure Node SDK enhancement we at Haufe-Lexware use to script things like backing up managed disks and such.

Most probably, this collection of tools may grow over time as soon as we need things.

Feel free to grab it if you want to, but we will not give any guarantee it works as you think it will.

## Usage

The toolset logs in using the Azure SDK, using a service principal. These values need to be passed in as environment variables:

Env Var | Description
--------|-------------
`SP_APPID` | The service principal's app ID ("username")
`SP_PASSWORD` | The service principal's app Secret ("password")
`SP_TENANTID` | The Tenant ID
`SUBSCRIPTION_ID` | The subscription ID to use

If these aren't passed in, expect weird error messages and nothing good happening (but nothing bad either).

## API

The `haufe-azure-arm-utils` exposes four more or less useful components:

```javascript
const armUtils = require('haufe-azure-arm-utils');

const armAccess = armUtils.access;
const diskUtils = armUtils.diskUtils;
const rgUtils = armUtils.resourceGroupUtils;
const filterUtils = armUtils.filterUtils;
```

### Component `diskUtils`

For easier management of managed disks in Azure.

#### `diskUtils.listDisks(resourceGroup, callback)`

Lists all disks in a resource group with the name `resourceGroup`.

Callback signature: `callback(err, diskList)`

#### `diskUtils.cloneDisk(diskSpec, targetGroupSpec, targetName, tags, callback)`

Clones a managed disk with the disk info spec `diskSpec` (from `listDisks`) into the resource group with the group spec `targetGroupSpec` (from `rgUtils.listGroups` or `getGroup`). The new cloned disk will have the name `targetName` and it wil be tagged with the entries from the json object `tags`.

Callback signature: `callback(err, newDiskSpec)`

#### `diskUtils.deleteDisk(resourceGroup, diskName, callback)`

Deletes the managed disk with the name `diskName` from the resource group `resourceGroup`.

Callback signature: `callback(err)`

### Component `rgUtils`

Manages resoucre groups.

#### `rgUtils.listGroups(callback)`

Returns the specs of all resource groups in the current subscription (to which the service principal has access).

Callback signature: `callback(err, groupList)`

#### `rgUtils.getGroup(name, callback)`

Returns the spec of a resource group with the given name.

Callback signature: `callback(err, groupSpec)`

### Component `filterUtils`

This is the part which is the most interesting perhaps, as it helps you do stuff with your resources.

#### `filterUtils.filterByTags(list, tags)`

Filters a list of resources by tags, given as an object.

Example:

```
const filteredList = filterUtils.filterByTags(diskList, { type: 'nfs' });
```

#### `filterUtils.getByName(list, name)`

Returns the item with the given `name`, if present. `null` otherwise.

#### `filterUtils.getNewest(list)`

Returns the item in the list with the latest `timeCreated` property.

#### `filterUtils.getKeepList(list, tags, [options])`

For backing up scenarios, use this method to find a list of resources you want to keep, using the following rules (based on `timeCreated` and the selection `tags`, see `filterByTags` for an example):

* Keep the newest resource all in all
* Keep today's latest resource
* Keep yesterday's latest resource
* Keep the latest resources from a specific day in the week, not older than a certain threshold
* Keep the resource created on the first day in a month, not older than a certain threshold

Use the optinal `options` parameter to tweak the behaviour; these are the default options:

```javascript
const FILTER_OPTIONS = {
    keepWeekly: true,
    weeklyDay: 3, // Wednesday
    weeklyThreshold: 14,
    keepMonthly: true,
    monthlyThreshold: 60
};
```

#### `filterUtils.getDeleteList(list, tags, [options])`

Reverse of `getKeepList`, renders a list of resources you can safely delete, according to your `options`.

### Component `access`

Usually, you don't need to use the `access` component manually; the usage is wrapped in the other components.

#### `access.getCredentials(callback)`

The function `getCredentials` logs in using the env var parameters above and returns credentials.

This function is usually wrapped inside the other two functions of `access` and does not need to be called explicitly.

Callback signature: `callback(err, credentials, subscriptionId)`

#### `access.getComputeClient(callback)`

Creates or returns a cached instance of the `ComputeManagementClient` class of the Azure Node SDK.

This function will automatically call `getCredentials` and retrieve credentials if this has not already happenened.

Callback signature: `callback(err, computeClient)`.

#### `access.getResourceClient(callback)`

Creates or returns a cached instance of the `ResourceManagementClient` class of the Azure Node SDK.

This function will automatically call `getCredentials` and retrieve credentials if this has not already happenened.

Callback signature: `callback(err, resourceClient)`.