Create IBM Cloud diagrams with enterprise tools using IBM Cloud Stencils.
Refer to the IBM Architecture Center for complete details.
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 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
- A GitHub.com account.
- Git CLI or GitHub Desktop.
- An SSH Key associated to the github.com account.
- 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:
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.
General
-
Instance Group feature is not currently available.
-
Floating IP icon is an arrow with a closed circle that represents a NIC pointing outwards from an instance.
-
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.
-
Diagram containers if available in a tool (draw.io and Visio) are used for boxes but not groups.
-
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
-
To use the IBM Stencils on draw.io in your browser: https://draw.io/?libs=ibm
-
To use the IBM Stencils on the draw.io desktop application do the following:
- Open application and click on "+ More Shapes" in the bottom left panel.
- Scroll down to the "Networking" section and check "IBM".
- Click "Apply" to finish.
IBM Stencils should now be available in the embedded categories in the left panel.
-
Template named ibm_vpc_architecture under Cloud on draw.io is currently outdated.
-
Folders for draw.io on this github are used for changes not on draw.io and are subject to change.
-
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.
-
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.
-
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.
-
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:
-
Issue #748 to remove container setting for groups.
Status: Open. -
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. -
Issue #839 to move labelBackgroundColor=none to after image; statement for IBM icons.
Status: Open.
Fixed Issues:
-
Issue #724 where icons dropped onto container in FF would not stay in container when container is moved.
-
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
-
Boxes are implemented as containers.
-
Box tags are currently separate and can optionally be placed on upper left corner of boxes.
Powerpoint
- Refer to all-ibm-cloud-architecture-icons-October2019-WithVPCUpdatesFebruary2020.pptx on this github.
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 |