diff --git a/knowledge base/best practices.md b/knowledge base/best practices.md index 04d74d5..8c504f3 100644 --- a/knowledge base/best practices.md +++ b/knowledge base/best practices.md @@ -1,50 +1,65 @@ # OAM best practices -Based on experience. +What really worked for me: -- Always think critically. +- Always think critically.
+ If you do/think things just bEcAuSe OtHeRs SaId So, all you're doing is admitting **both** that you know no better **and** that you're not willing to consider otherwise. - The _one-size-fits-all_ approach is a big fat lie.
- This proved particularly valid with regards to templates and pipelines. -- Apply the KISS approach wherever possible, not to keep _all_ things simple but as an invite to keep things simple **with respect of your ultimate goal**.
- Be aware of simplicity for the sake of simplicity, specially if this makes things complicated on a higher level. + You'll end up with stiff, hard to change results that satisfy nobody. This proved particularly true with regards to templates and pipelines. +- Apply the KISS approach wherever possible.
+ Consider it not as _keeping all things simple because they need to be simple_, but as an invite to keep things simple **with respect of your ultimate goal**.
+ Beware of simplicity for the sake of simplicity, specially if this makes things complicated on a higher level. Check out [KISS principle is not that simple]. +- Beware of complex things that sHoUlD bE sImPlE.
+ Check out the [SAFe] delusion. - There is no perfect nor correct solution, just different sets of tradeoff.
Find the one that most satisfies you and your **current** necessities. -- Review every decision after some time. Check they are still relevant, or if there is some improvement you can implement. - Things change constantly: new technologies are given birth often, and processes improve.
+- Review every decision after some time. Check they are still relevant, or if there is some improvement you can implement.
+ Things change constantly: new technologies are given birth often, and processes improve. - Focus on what matters, but also set time aside to check up the rest.
- Mind the Pareto principle (_80-20 rule_, roughly 80% of consequences come from 20% of causes). -- Automate when and where you can, yet mind [the automation paradox]. -- Keep things **de**coupled where possible, the same way _interfaces_ are used in programming.
+ Check [Understanding the pareto principle (the 80/20 rule)]. +- Learn from your (and others') mistakes. +- Put in place processes to avoid repeating mistakes.
+ Check out the [5 whys] approach. +- Automate when and where you can, yet mind [the automation paradox].
+ Check also out [`pre-commit`][pre-commit]. +- Keep things **de**coupled where possible, the same way [_interfaces_ are used in programming][what does it mean to program to interfaces?].
This allows for quick and (as much as possible) painless switch between technologies. - Choose tools based on **how helpful** they are to achieve your goals.
Do **not** adapt your work to specific tools. -- Backup your data.
- Especially when you are about to update something. [Murphy's law] is lurking. +- Backup your data, especially when you are about to update something.
+ [Murphy's law] is lurking. Consider [the 3-2-1 backup strategy]. - [Branch early, branch often]. - [Keep changes short and sweet][the art of small pull requests].
Nobody likes to dive deep into a 1200 lines, 356 files pull request ([PR fatigue][how to tackle pull request fatigue], everybody?). -- Make changes easy, avoid making easy changes. -- [Trunk-based development][trunk-based development: a comprehensive guide] and other branching strategies all work but [have different pros and cons][git branching strategies vs. trunk-based development]. +- Consider keeping changes in _behaviour_ (logic) separated from changes to the structure.
+ It allows for easier debugging by letting you deal with one great issue at a time. +- Make changes easy, avoid making easy changes.
+ Easy changes will build up long term and become a pain to deal with. +- [Trunk-based development][trunk-based development: a comprehensive guide] and other branching strategies all work.
+ Consider the [different pros and cons of each][git branching strategies vs. trunk-based development]. - Refactoring _can_ be an option.
- But do **not** use it mindlessly. + Just **don't** use it mindlessly. - _DevOps_, _GitOps_ and other similar terms are sets of practices, suggestions, or approaches.
They are **not** roles or job titles.
They are **not** to be taken literally.
They **need** to be adapted to the workplace, not the other way around. - Be aware of [corporate bullshit][from inboxing to thought showers: how business bullshit took over]. -- [Amazon's leadership principles] are double-edge swords and only Amazon can apply them as they are defined. -- Watch out for complex things that should be simple (i.e. the [SAFe] delusion). +- [Amazon's leadership principles] are double-edge swords.
+ Only Amazon was able to apply them as they are defined, and they still create a lot of discontent. - Keep _integration_, _delivery_ and _deployment_ separated.
They are different concepts, and as such should require different tasks.
This also allows for checkpoints, and to fail fast with less to no unwanted consequence. +- All pipelines' tasks should be able to execute from one's own local machine. - Keep pipelines' tasks as simple, consistent and reproducible as possible.
- Avoid like the plague to put programs or scripts in pipelines: they should be glue, not applications. -- Pipelines' tasks should be able to execute from one's own computer. + Avoid like the plague to put programs or scripts in pipelines: they should be _glue_, not applications. - Pipelines are meant to be used as **last mile** steps for specific goals.
- There **cannot** be a single pipeline for everything, the same way as _one-size-fits-all_ is a big, fat lie. + There **cannot** be a single pipeline for everything, the same way as _one-size-fits-all_ never works. ## Sources +In order of addition: + +- Personal experience - [A case against "platform teams"] - [Culture eats your structure for lunch] - [DevOps is bullshit] @@ -61,16 +76,23 @@ Based on experience. - [From inboxing to thought showers: how business bullshit took over] - [Simple sabotage for software] - [Hacking your manager - how to get platform engineering on their radar] +- [KISS principle is not that simple] by William Artero +- [What does it mean to program to interfaces?] by Attila Fejér +- [Understanding the pareto principle (the 80/20 rule)] +- [The 3-2-1 backup strategy] by Yev Pusin +- [5 whys] +[pre-commit]: pre-commit.md [safe]: safe.placeholder [the automation paradox]: the%20automation%20paradox.md +[5 whys]: https://www.mindtools.com/a3mi00v/5-whys [a case against "platform teams"]: https://kislayverma.com/organizations/a-case-against-platform-teams/ [amazon's leadership principles]: https://www.amazon.jobs/content/en/our-workplace/leadership-principles [amazon's tenets: supercharging decision-making]: https://aws.amazon.com/blogs/enterprise-strategy/tenets-supercharging-decision-making/ @@ -81,10 +103,14 @@ Based on experience. [git branching strategies vs. trunk-based development]: https://launchdarkly.com/blog/git-branching-strategies-vs-trunk-based-development/ [hacking your manager - how to get platform engineering on their radar]: https://www.youtube.com/watch?v=8xprsTXKr0w [how to tackle pull request fatigue]: https://javascript.plainenglish.io/tackling-pr-fatigue-6865edc205ce +[kiss principle is not that simple]: https://artero.dev/posts/kiss-principle-is-not-that-simple/ [murphy's law]: https://en.wikipedia.org/wiki/Murphy%27s_law [platform teams need a delightfully different approach, not one that sucks less]: https://www.chkk.io/blog/platform-teams-different-approach [simple sabotage for software]: https://erikbern.com/2023/12/13/simple-sabotage-for-software.html +[the 3-2-1 backup strategy]: https://www.backblaze.com/blog/the-3-2-1-backup-strategy/ [the art of small pull requests]: https://essenceofcode.com/2019/10/29/the-art-of-small-pull-requests/ [trunk-based development: a comprehensive guide]: https://launchdarkly.com/blog/introduction-to-trunk-based-development/ +[understanding the pareto principle (the 80/20 rule)]: https://betterexplained.com/articles/understanding-the-pareto-principle-the-8020-rule/ [we have used too many levels of abstractions and now the future looks bleak]: https://unixsheikh.com/articles/we-have-used-too-many-levels-of-abstractions-and-now-the-future-looks-bleak.html +[what does it mean to program to interfaces?]: https://www.baeldung.com/cs/program-to-interface [why the fuck are we templating yaml?]: https://leebriggs.co.uk/blog/2019/02/07/why-are-we-templating-yaml diff --git a/knowledge base/the automation paradox.md b/knowledge base/the automation paradox.md index 2eb6d9b..2feff3c 100644 --- a/knowledge base/the automation paradox.md +++ b/knowledge base/the automation paradox.md @@ -1,28 +1,30 @@ # The automation paradox The point of automation is to reduce the manual workload.
-It's goals are also to maintain consistency and reliability of infrastructure and processes. +Its goals include also maintaining the consistency and reliability of infrastructure and processes. The issue: - For every automation one puts in place, a _system_ is created.
- Such system is the automation itself of the set of tools used to create it. -- A system needs configuration and maintenance. -- One relies on systems to maintain other systems. -- Complex systems trend toward _brittle_ and _expensive_.
- Especially true when one uses imperative runbooks.
+ Said system is either the automation itself or the set of tools used to create it. +- Any system needs proper configuration and maintenance. +- No matter how, one always ends up relying on systems to maintain other systems.
+ Re-read the first point in this list to remember why. +- Complex systems trend toward being _brittle_ and _expensive_.
+ This point is especially true when using imperative runbooks.
Google [_Software crisis_][software crisis] for more info. -- The need to manage such complexity gave birth to a whole cottage industry.
+- The need to manage complexity gave birth to a whole cottage industry.
This includes tools and specific job titles (i.e. _DevOps_, _SRE_). -- The tools one choses to implement one's system need to be consistent and reliable.
- Should they not be, their issues defeat the whole purpose of what one is trying to automate. +- The tools used to implement one's system need to be consistent and reliable.
+ Should they not be, their issues defeat the whole purpose of the automation. Possible solutions: - Move from imperative to declarative (desired state) where one can.
Check out [the _GitOps_ approach][gitops]. - Apply the KISS approach where possible.
- Make it so that is simple to maintain, not necessarily simple for the sake of simplicity. + Make it so that is simple to maintain, not necessarily simple for the sake of simplicity.
+ Check out [KISS principle is not that simple]. - Focus on the tools that most allow one to simplify the automation.
Dependent on the final goals. - Limit abstractions.
@@ -30,11 +32,12 @@ Possible solutions: ## Sources -- Personal experience. +- Personal experience - [Automating your source of truth - GitOps and Terraform] - [Software crisis] - [We have used too many levels of abstractions and now the future looks bleak] -- [Why the fuck are we templating yaml?] +- [Why the fuck are we templating yaml?] by Lee Briggs +- [KISS principle is not that simple] by William Artero [automating your source of truth - gitops and terraform]: https://www.youtube.com/watch?v=-K8R1OVXPy0 +[kiss principle is not that simple]: https://artero.dev/posts/kiss-principle-is-not-that-simple/ [software crisis]: https://www.geeksforgeeks.org/software-engineering-software-crisis/ [we have used too many levels of abstractions and now the future looks bleak]: https://unixsheikh.com/articles/we-have-used-too-many-levels-of-abstractions-and-now-the-future-looks-bleak.html [why the fuck are we templating yaml?]: https://leebriggs.co.uk/blog/2019/02/07/why-are-we-templating-yaml.html