npm package: @jpmonge86/ibm_cloud_stencils_sem_release
Description: [![Build Status](https://travis.ibm.com/ibmcloud/ibm-cloud-stencils.svg?token=Vtzz2sns43Wqm8Q6XBru&branch=master)](https://travis.ibm.com/ibmcloud/ibm-cloud-stencils) [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semanti
Latest version: 1.3.1
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

# IBM Cloud Stencils

[![Build Status](https://travis.ibm.com/ibmcloud/ibm-cloud-stencils.svg?token=Vtzz2sns43Wqm8Q6XBru&branch=master)](https://travis.ibm.com/ibmcloud/ibm-cloud-stencils) [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release) 

Create IBM Cloud diagrams using Draw.io tool with IBM Cloud Architecture Stencils.  

This is an internal repository oriented to IBMers, which can include special / particular guidance, stencils and tools for offerings not yet officially announced or released.

# IBM v1.1 Stencils

IBM Stencils version 1.1 currently is the recommended version for sketching diagrams, for more information on obtaining and using this, see the respective labeled sections (below).

## Importing Stencil v1.1 Libraries into Draw.io

This easy guide provides instructions to import stencils published in this repository (**drawio folder**) into draw.io.
Stencils/icons are added and grouped using libraries, the libraries can contain one or several stencils, these are saved and generated in XML format (.xml). To use these these custom libraries, they first must be imported in order to make them available in the draw.io utility. Remember that only desktop drawio application is authorized for IBM internal diagrams.

### Import Guides

<details><summary>Import using Github Clone (Recommended)</summary>
<p>

### Prerequistes

- A [GitHub.com account](https://github.com/).
- Git [CLI](https://gist.github.com/derhuerst/1b15ff4652a867391f03) or [GitHub Desktop](https://desktop.github.com/).
- An [SSH Key associated](https://help.github.com/en/githubauthenticating-to-github/adding-a-new-ssh-key-to-your-github-account) to the github.com account.
 
### Instructions

- Sign into [github](https://github.com/login?return_to=%2Fibm-cloud-architecture%2Fibm-cloud-stencils).
- While in the main [page](https://github.com/ibm-cloud-architecture/ibm-cloud-stencils), click the **Clone or download** button, select on **Use SSH** if not already selected (**Use HTTPS** will be displayed) and then copy the link using the copy symbol:

![](images/UseSSH.png)

- CD to directory where you wish to clone this repository.

- Clone the repository using **git clone** syntax using the previously copied ssh link:

```
$ git clone git@github.com:ibm-cloud-architecture/ibm-cloud-stencils.git
Cloning into 'ibm-cloud-stencils'...
Enter passphrase for key '/Users/youruserid/.ssh/id_rsa': 
```
- Enter the passphrase of your SSH key.

- Confirm repository was successfully cloned, the CLI should display something like this:

```
remote: Enumerating objects: 58893, done.
remote: Total 58893 (delta 0), reused 0 (delta 0), pack-reused 58893
Receiving objects: 100% (58893/58893), 185.09 MiB | 5.01 MiB/s, done.
Resolving deltas: 100% (18944/18944), done.
$ 
```
- Optionally use GitHub Desktop to Clone. In the main [page](https://github.com/ibm-cloud-architecture/ibm-cloud-stencils), click the **Clone or download** button, select on **Open in Desktop**, wait for the prompt and select/confirm launching the link using GitHub Desktop application. Confirm directory where repository will be cloned:

  ![](images/CloningUsingGHD.png)

  Click on **Clone** and wait for process to complete.

- Open the desktop [Draw.io application](https://github.com/jgraph/drawio-desktop/releases) in your computer or open [draw.io](https://www.draw.io/) in your browser.

- Select **Create New Diagram**, then click **Create**.

- Click on **File > Open Library**, browse your drawio folder in your cloned/local  directory and select the XML file, then click on **Open**. Repeat for every additional XML file you wish to import.

- Confirm library or libraries are visible in the left panel:

![](images/ImportedLibraries.png)

</p>
</details>
<details><summary>Import using Download Zip</summary>
<p>

- To download all contents of the repository, navigate to the main [page](README.md), click the **Clone or download** button and then select **Download ZIP**.

- Go to your downloads directory and extract the ZIP file contents and access the folder called **drawio**, it should be located in the following path:

`YourDownloadsDirectory/ibm-cloud-stencils-master/drawio`

- Confirm XML file(s) you wish to import are visible inside the the drawio folder in your downloads directory:

![](/images/ConfirmXMLfiles.png)

- Open the desktop [Draw.io application](https://github.com/jgraph/drawio-desktop/releases) in your computer or open [draw.io](https://www.draw.io/) in your browser.

- Select **Create New Diagram**, then click **Create**.

- Click on **File > Open Library**, browse your drawio folder in your downloads directory and select the XML file, then click on **Open**. Repeat for every additional XML file you wish to import.

- Confirm library or libraries are visible in the left panel:

![](images/ImportedLibraries.png)

If you run into issues, please use Github Clone approach (below)
</p>
</details>

# Using IBM Cloud Stencils

## Overview

IBM stencils/shapes can be of any of the following formats
- Boxes (under / as `groups` too) which represent a deployedOn relationship for locations (logical, virtual, physical) of platforms, infrastructure, network, etc, on which services and applications are deployed.
- Groups  which represent a deployedTo relationship for grouping services and applications deployed on boxes.
- Nodes which are meant to represent standalone components or devices.

For example, a virtual server instance is deployed on a subnet and deployed to a security group. 

The stencils are also organized by type, function and/or purpose using the following categories:

  * IBM (Core): Components that are typically technology and brand independent and/or not associated with an specific IBM Cloud offering/service. Examples: Server, Router, Database, Application
  * IBM Cloud: IBM Cloud specific offerings and services. Examples: IBM VPC, Classic VSI, Serverless, Internet Services, Security-Group.
  * IBM Domains/Industries: Extensions focused on IBM specific non-Cloud domains and industries. Examples: Automotive, Retail, Blockchain, Watson.
  * 3rd Party: Third party products/services. Examples: VMware, BigFix, Akamai.

## v1.1

Version 1.1 refers to an extension to legacy IBM stencils available in the drawio application, some of which were either enhanced or replaced. 1.0 is only recommended when shapes are not available in 1.1.

Current icons/stencils consist of:
- [X] [Architecture Icons](https://www.ibm.com/cloud/architecture/architectures/edit) which represent IBM Cloud specific and non-cloud specific components organized and categorized by type, function and color.

See all available v1.1 stencils in SVG format in the [**Architecture SVG Database** folder](Architecture%20SVG%20Database). 
- [ ] [Catalog Service Icons](https://github.ibm.com/CloudEngineering/ibm_cloud_architecture/) which represent mostly legacy stencils for services available in the IBM Cloud catalog. These stencil (.xml) libraries are identified with **ibm_cloudcatalog_** prefix. Consolidated library can be downloaded from [here](https://l2fprod.github.io/myarchitecture/).

_Note:_
- [X] _Recommended as primary sketching method/source of stencils. Catalog Service Icons are to be used only if not available in Architecture Icons libraries_.

### v1.1 Examples

<details><summary>IBM VPC Diagram using latest v1.1 stencils and connector standards</summary>
<img src="/images/ibm_vpc_architecture_simple.png">
</details>

### v1.1 Templates

Find latest templates in [drawio/templates/v1.1](https://github.ibm.com/ibmcloud/ibm-cloud-stencils/tree/master/drawio/templates/v1.1)

## v2.0

A new version of stencils is currently being developed and getting ready for its official release.
### Compatible with [draw.io application](https://github.com/jgraph/drawio-desktop/releases)

If you need to use 2.0 shapes compatible/importable with/in desktop drawio application, a static version (same look and feel but no extended features of build) of the stencils has been made available under [drawio/stencils/2.0](https://github.ibm.com/ibmcloud/ibm-cloud-stencils/tree/master/drawio/stencils/2.0) in this repository. To import the libraries follow the instructions in the [import guide](https://github.ibm.com/ibmcloud/ibm-cloud-stencils#importing-stencil-v11-libraries-into-drawio).

Note: IBM (Deprecated) refers to legacy icons of version 1.0, which is no longer used or recommended in any case/context.

### Temporary /custom build
 To access the latest pre-release (temporary binary for Mac) go [here](https://github.ibm.com/ibmcloud/ibm-cloud-stencils/releases/tag/v30.2.56-ibm2beta2), download the zip/dmg and extract the binary, then do the following:

* Open application/binary and click on "+ More Shapes" in the bottom left panel.
* Scroll down and select/check "IBM" or the respective libraries ("IBM Cloud", "IBM Core", "IBM Industry", etc.) if using Beta 1 .
* Click "Apply" to finish.

:warning: Note that this binary is a custom extended version of the official drawio desktop application, where 2.0 features and properties have been added, however, despite it looks and behaves like it, it is not backwards compatible with native drawio diagrams and stencils, which means diagrams/stencils built in 2.0 cannot be imported in desktop drawio application. 

### v2.0 Examples

<details><summary>IBM Kubernetes Service in a Classic Single-Region Multi-Zone environment using v2.0 stencils and latest connector standards</summary>

  ![](images/v2.0/Static/IKS_SR_MZ_Classic.svg)
</details>
<details><summary>IBM Red Hat OpenShift Service in a VPC Single-Region Multi-Zone environment using v2.0 stencils and latest connector standards</summary>

  ![](images/v2.0/Static/ROKS_SR_MZ_VPC.svg)
</details>
<details><summary>IBM Red Hat OpenShift Service in a Classic Single-Region Multi-Zone environment using v2.0 stencils and latest connector standards</summary>

  ![](images/v2.0/Static/ROKS_SR_MZ_Classic.svg)
</details>

### v2.0 Templates

Find latest templates in [drawio/templates/v2.0](https://github.ibm.com/ibmcloud/ibm-cloud-stencils/tree/master/drawio/templates/v2.0).
If using beta2 build (`vXXYY-ibm2beta2`), check out also the "IBM Starters" library to access common pre-built layouts that can be useful as starting points for diagrams.


## Tools & Conventions

<details><summary>draw.io</summary>
<p>

**NOTE: For IBM internal designs/diagrams, you must use the desktop application (2.) to create or edit a diagram. The draw.io/diagrams.net web application (1.) is only approved for public designs that contain no forward-looking material**
1. To use the IBM Stencils on draw.io in your browser: https://draw.io/?libs=ibm
2. To use the IBM Stencils on the [draw.io desktop application](https://github.com/jgraph/drawio-desktop/releases) follow [above instructions](https://github.ibm.com/ibmcloud/ibm-cloud-stencils#importing-stencil-v11-libraries-into-drawio) for importing stencil libraries (.xml files)

</p>
</details>

<details><summary>System Architecture Standards/Conventions</summary>
<p>

Please see the [system architecture](https://github.ibm.com/CloudEngineering/system_architecture/tree/master/docs/arch_doc#architecture-documentation-conventions) for details

</p>
</details>

<details><summary>Connectors</summary>
<p>

  ![](images/Connectors.svg)
  
Please see the [Connectors file](https://github.ibm.com/ibmcloud/ibm-cloud-stencils/blob/master/drawio/Connectors.drawio) with draw.io format version of the picture above or import the [IBM Connectors xml library](https://github.ibm.com/ibmcloud/ibm-cloud-stencils/blob/master/drawio/stencils/ibm_connectors.xml).

</p>
</details>