Asciidoc

The AWS shapes are included in the PlantUML stdlib .. simply include them as shown here: example.puml @startuml !include <awslib/AWSCommon> !include <awslib/Analytics/ManagedStreamingforKafka> !include <awslib/Database/RDS> !include <awslib/General/Users> !include <awslib/General/InternetGateway> !include <kubernetes/k8s-sprites-labeled-25pct> skinparam linetype ortho title "AWS Context Diagram" package "EKS Kubernetes Cluster" as eks_cluster { component "<$pod>\napp1" as pod1 component "<$pod>\napp2" as pod2 } ManagedStreamingforKafka(kafka_pod, "Amazon MSK", "Apache Kafka") RDS(pg_rds, "PostgreSQL", "Sample Schema") Users(users, "AppUsers","editors, admins") InternetGateway(igw1, "Customer Gateway", "Customer access to internal services") users -> igw1 igw1 --> pod1 igw1 --> pod2 pod1 --> pg_rds pod1 --> kafka_pod pod2 --> pg_rds pod2 --> kafka_pod @enduml ...

C4 models allow us to visualize software architecture by decomposition in containers and components. Viewpoints are organized in hierarchical levels: Context Diagrams (Level 1) Container Diagrams (Level 2) Component Diagrams (Level 3) Code Diagrams (Level 4) C4-PlantUML offers a variety of macros and stereotypes that make modeling fun. An example in PlantUML: sample.puml @startuml !include <c4/C4_Context.puml> !include <c4/C4_Container.puml> left to right direction Person(user, "User") System_Ext(auth, "AuthService", "Provides authentication and authorization via OIDC") System_Boundary(zone1, "Some system boundary") { System(lb, "Load Balancer") System_Boundary(az, "App Cluster") { System(app, "App Servers") { Container(app1, "App1", "Docker", "Does stuff") Container(app2, "App1", "Docker", "Does stuff") ContainerDb(dbSess, "Session DB", "Redis") ContainerDb(db1, "RBMS 1", "AWS RDS Postgres") ContainerDb(db2, "RBMS 2", "AWS RDS Postgres") ' both app servers sync sessions via redis Rel(app1, dbSess, "Uses", "Sync Session") Rel(app2, dbSess, "Uses", "Sync Session") ' both app servers persist data in RDBMS Rel(app1, db1, "Uses", "Persist/query relational data") Rel(app2, db2, "Uses", "Persist/query relational data") } } } Rel(user, lb, "call") Rel(lb, app1, "delegate") Rel(lb, app2, "delegate") Rel(app1, auth, "Verify", "User auth") Rel(app2, auth, "Verify", "User auth") SHOW_FLOATING_LEGEND() @enduml ...

I have written about other software system analyzing and validation tools before but today I would like to introduce a new tool named jqAssistant that supports software architects, developers and analysts in a variety of tasks like analyzing given structures, validating architectural or quality constraints and generating reports. Therefore jqAssistant analyzes given projects or artifacts and stores the gathered information – that is enriched by a variety of existing plugin-ins – in a Neo4j graph database. ...

A variety of different tools exists to help us analyze RESTful web-services and create documentations for their APIs in different formats. In the following tutorial I’d like to demonstrate how to document an existing JAX-RS web-service in multiple formats like Swagger, AsciiDoc or Plain Text using Maven, the JAX-RS Analyzer and the JAX-RS Analyzer Maven Plugin. The JAX-RS Analyzer gathers its information not only by reflection like most other tools but also by bytecode analysis and therefore does not require us to add special annotations for documentation to our code. ...

Inspect Docker Image with dive Install dive brew install dive Now we can run dive against any Docker image we wish to inspect…​ Run dive dive confluentinc/cp-kafka:5.4.3 Figure 1. Screenshot of dive analyzing the Kafka Docker image Resources: dive on GitHub Introspect Private Docker Registry List images: curl -s https://the-registry-url/v2/_catalog Get tags for an image curl -s https://the-registry-url/v2/the-image-name/tags/list An example: curl -s https://registry.local/v2/alpine/rabbitmq/tags/list {"name":"alpine/rabbitmq","tags":["3.9.17"]} Run Trivy Scan for Docker Image docker run aquasec/trivy image IMAGE:TAG ...

Generate AsciiDoc Documentation and Publish it with GitLab Pages We setup a repository and add a directory named docs there .. this is the home of our AsciiDoc files. We’re using asciidoctor/docker-asciidoctor as Docker image for tool provisioning This is the .gitlab-ci.yml, we’re running the stage only when something in the docs directory has changed. stages: - "Build docs" # The name of the job activates the GitLab pages publication pages: image: asciidoctor/docker-asciidoctor stage: "Build docs" tags: - build script: - sh ./gen_docs.sh - mv output public only: refs: - master changes: - /docs/* artifacts: paths: - public expose_as: 'Documentation Archive' ...