yulifan2020/ibm-cloud-stencils

IBM Cloud Stencils for creating IBM Cloud diagrams with popular diagram tools.

IBM Cloud Stencils

Create IBM Cloud diagrams with enterprise tools using IBM Cloud Stencils.
Refer to the IBM Architecture Center for complete details.

Importing Stencil 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.

Import Guides

Import using Download Zip

• To download all contents of the repository, navigate to the main page, 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:

• Open the desktop Draw.io application in your computer or open 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:

Import using Github Clone

Prerequistes

• A GitHub.com account.
• Git CLI or GitHub Desktop.
• An SSH Key associated to the github.com account.

Instructions

• Sign into github.
• While in the main page, 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:

• 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 [email protected]: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, 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:

  

  Click on Clone and wait for process to complete.

• Open the desktop Draw.io application in your computer or open 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:

Using IBM Cloud Stencils

Overview

IBM Cloud deployment diagrams are organized by:

• Boxes 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.

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

IBM Cloud deployment diagram icons consist of:

• Architecture Icons which represent IBM Cloud components by background color.
• Service Icons which represent services available in the IBM Cloud catalog.

Examples

IBM VPC Diagram

Notes

General

1. Instance Group feature is not currently available.

2. Floating IP icon is an arrow with a closed circle that represents a NIC pointing outwards from an instance.

3. IBM VPC has a single subnet type Subnet where Subnet:ACL denotes a Subnet with an associated ACL which can be customized such as SubnetName:ACLName, SubnetCIDR:ACLName, split to 2 lines, etc.

4. Diagram containers if available in a tool (draw.io and Visio) are used for boxes but not groups.

5. To migrate existing boxes and groups to latest, apply styles from new boxes and groups to existing diagram. For draw.io, updating styles in existing boxes that are not yet containers won't make existing contents of a box part of the container.

draw.io

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 do the following:

   1. Open application and click on "+ More Shapes" in the bottom left panel.
   2. Scroll down to the "Networking" section and check "IBM".
   3. Click "Apply" to finish.

   IBM Stencils should now be available in the embedded categories in the left panel.

3. Template named ibm_vpc_architecture under Cloud on draw.io is currently outdated.

4. Folders for draw.io on this github are used for changes not on draw.io and are subject to change.

5. Boxes are containers (container=1). Groups are not containers (container=0). Temporary step to set container=0 (in style or uncheck property) for the groups. See open issue #1.

6. When adding icons to diagrams the default background color for text should be transparent but instead may be white. See open issue #2 and #3.

7. When exporting diagrams to svg ensure that icons are included (check Embed Image) if using svg offline and ensure white space is minimal (select entire diagram then check Selection Only and Crop) if embedding in a document.

8. A new property Resize Children with default checked (corresponds to recursiveResize=1 in style) was added recently by draw.io. Our boxes now set recursiveResize=0 otherwise the contents of boxes are resized whenever the boxes are resized. Existing diagrams have recursiveResize=1 set so if the diagram will be changed consider setting recursiveResize=0 in the style or uncheck Resize Children for boxes.

Open Issues:

1. Issue #748 to remove container setting for groups.
   Status: Open.

2. Issue #620 where setting the icon text background to transparent doesn't work.
   Status: Open. This issue happens if labelBackgroundColor=none is before the image; statement in icon style, so place the labelBackgroundColor=none to anywhere after the image; statement.
   

3. Issue #839 to move labelBackgroundColor=none to after image; statement for IBM icons.
   Status: Open.

Fixed Issues:

1. Issue #724 where icons dropped onto container in FF would not stay in container when container is moved.

2. Issue #723 where overlaying a box across other boxes may cause underlying boxes to expand and have to be resized such as when placing a security group box across multiple subnet boxes. This scenario is working as designed so draw.io added a new property "expand" to swimlanes for our boxes. The current behavior is the default with expand=1 and our boxes are set to expand=0.

Visio

1. Boxes are implemented as containers.

2. Box tags are currently separate and can optionally be placed on upper left corner of boxes.

Powerpoint

1. Refer to all-ibm-cloud-architecture-icons-October2019-WithVPCUpdatesFebruary2020.pptx on this github.

Standards

Colors

Style	Hex Color	RGB Color
Text (Helvetica 12 pt)	#000000	0,0,0
Connectors (1 pt and 2 pt)	#000000	0,0,0
Blue Borders	#4376BB	67,120,187
Light Blue Fill	#CDEBF9	80,92,98
Green Borders	#00882B	0,136,43
Light Green Fill	#E6F0E2	230,240,226
Grey Borders	#919191	145,145,145
Light Grey Fill	#E0E0E0	224,224,224
Purple Borders	#B99ACD	185,154,205
Light Purple Fill	#F0E8FF	245,232,255
Red Borders	#FF0000	255,0,0
Gold Borders	#C4982E	196,152,46

Boxes

Name	Icon	Icon Name	Style	Width	Type
IBM Cloud		CloudTag	Solid Blue Border	3 pt	Container
VPC		VPCTag	Solid Blue Border	2 pt	Container
Region		RegionTag	Solid Grey Border	2 pt	Container
Zone		ZoneTag	Solid Grey Border Light Grey Fill	1 pt	Container
Subnet		SubnetTag	Solid Green Border Light Green Fill	1 pt	Container
Bare Metal Server		BareServerTag	Solid Green Border	2 pt	Container
Virtual Server		VirtualServerTag	Solid Green Border	2 pt	Container
Classic Infrastructure		ClassicTag	Solid Blue Border	2 pt	Container
Public Network		PublicTag	Solid Blue Border	3 pt	Container
Enterprise Network		EnterpriseTag	Solid Blue Border	3 pt	Container
Cloud Services		CloudServiceTag	Solid Blue Border	1 pt	Container
Cloud Foundry		FoundryTag	Solid Blue Border	2 pt	Container
IBM Kubernetes Cluster		KubeTag	Solid Blue Border	2 pt	Container
General Kubernetes Cluster		GeneralKubeTag	Solid Blue Border	2 pt	Container
OpenShift Cluster		OpenShiftTag	Solid Blue Border	2 pt	Container
Kubernetes Service		KubeServiceTag	Solid Blue Border	2 pt	Container
Kubernetes Replica Set		KubeReplicaTag	Solid Blue Border Light Blue Fill	2 pt	Container
Kubernetes Pod		KubePodTag	Solid Purple Border Light Purple Fill	2 pt	Container

Groups

Name	Icon	Icon Name	Style	Width	Type
Kubernetes Namespace Group		KubeGroupTag	Dashed Blue Border	2 pt	Non-container
Account Group		AccountGroupTag	Dashed Gold Border	2 pt	Non-container
Instance Group		InstanceGroupTag	Dashed Green Border	2 pt	Non-container
Resource Group		ResourceGroupTag	Dashed Grey Border	2 pt	Non-container
Security Group		SecurityGroupTag	Dashed Red Border	2 pt	Non-container

References

1. IBM Terraform Provider
2. Terraformer for VPC