Get our SSP system overview sections up-to-date

[brittag]

In order for Technical Reviewers to understand our system, we should ensure our system overview sections of the SSP (9-10) reflect our system very well, especially areas that they had questions about.

Setup

Read the guidance in HOWTO update the SSP before working on this.

The relevant SSP chunk Google Docs are here:

• 9 - General System Description
• 10 - System Environment

Acceptance criteria

The following high-priority tasks all derive from the JAB reviewer items (additional notes here) - see those documents for more details.

• [x] Section 10 (System Environment) includes a section describing Buildpacks, the customer responsibility for using supported ones, and a deep link to documentation on how each specific buildpack can be configured by the user. (https://github.com/18F/cg-docs/issues/399 may be helpful.) [JAB item 5]
• [x] Section 10 (System Environment) includes a section describing how secrets are communicated from the platform to applications (eg via environment variables) [JAB item 5]
• [x] Section 10.3.2 (System Environment) includes a summary of where firewall rules are implemented (AWS Security Groups are applied at the AWS level, Application Security Groups are applied as iptables in the network namespaces of the application container). Note: When you work on this, check with the AC implementer about their status (https://github.com/18F/cg-compliance/issues/176) since they have related work to do on AC items. [JAB item 6]
• [x] Section 10 (System Environment) includes a container definition and details about how container security works (kernel ABI namespacing) [JAB item 7]

We also need to update our Section 10.7 (Data Flow) - this is filed as its own story at https://github.com/18F/cg-product/issues/291

We also need to update our Section 9.3 "Types of Users" table - this is filed as its own story at https://github.com/18F/cg-compliance/issues/165

In general, we also need to check the overall status of sections 9 and 10 and make sure they reflect our system accurately, summarizing all the major components of cloud.gov.

• [x] Section 9 is updated to reflect our system accurately.
• [x] Section 10 is updated to reflect our system accurately.

[brittag]

@wslack put in some review comments/suggestions to point out ways to make Section 9 make more sense to readers - thanks Will!

[wslack]

I reviewed section 9 and left some edits and comments. There's a lot of vocabulary referenced that may need to be explained, and Noah has some comments to review, but it's in decent shape. It will need to be checked by someone with full system knowledge, probably Diego given the descriptions of roles.

I also reviewed section 10, accepted some edits, and made a few others. Section 10 assumes auth to cloud.gov using GitHub credentials; is that the expectation? It will need to be be checked by someone with full system knowledge for authenticity but the writing (while dense) is solid.

Generally, there is some content discussed in both documents. Is 9 a summary of 10, or should the content be in one doc only? Do they have different audiences?

[brittag]

For the "Section 10 (System Environment) includes a section describing Buildpacks" item, I reviewed the current effort at this (a very good start) and added a draft table with more details. I'm not entirely sure that draft table achieves exactly what we need to achieve.

@wslack In the full SSP, readers will read Section 9 and then Section 10. We have the same audience for these sections: the basic goal is that the JAB TRs should be able to read these two sections to get a strong start for understanding the overall cloud.gov system. In other words: these sections shouldn't repeat each other too much, but some repetition is ok if it helps the readers understand key points.

[brittag]

Review status: these two sections would be great for @mogul to review against two major goals: (1) are these sections satisfying the specific things the TRs asked for, as listed in the first set of ACs here? (2) do these sections make sense overall, as listed in the second set of ACs? (Feel free to accept any reasonable changes as you read, so that we can have a clearer view of what needs further review.)

[mogul]

Thanks to @LinuxBozo for his extensive edits! I've raked it through quite a bit now. Per the comments, there are a few points still to follow up on but I think it's worth getting external eyes so I've pointed Bridget at it while we continue to resolve these points.

[LinuxBozo]

Diagrams being re-done and deployed: https://diagrams.fr.cloud.gov Source: https://github.com/18F/diagrams-app

[mogul]

I've significantly reworked the narrative in a bunch of ways that made me happier with how it flows. Finishing the user types table and the service list are separate stories. The only thing left within the scope of this story is the diagram work, which @LinuxBozo is working on.

@rjbator, this is ready for greater scrutiny on the narrative side. Can you please start on that even while Adam is working on the diagrams so we can get this closed sooner rather than later?

[rjbator]

Yes I will start on reviewing / commenting on this today.

[mogul]

I dropped in a few references between sections and the diagrams in the "data flow" section that help illustrate them, but they're not all 1:1. I'm wondering if it's worth the effort to rearrange the diagrams and the text that refers to them into distinct sections...?

[mogul]

@NoahKunin note that a few diagram changes from @LinuxBozo are still blocked on you releasing the boundary diagram.

[brittag]

We submitted this.