Save 37% off PRO during our Black Friday Sale! »

Continuous Documentation - CI/CDパイプラインを活用した文書化技術 - / Pepabo Tech Conference #16

Continuous Documentation - CI/CDパイプラインを活用した文書化技術 - / Pepabo Tech Conference #16

69b93af68320a590f607c296e8edff73?s=128

Ken’ichiro Oyama

September 28, 2021
Tweet

Transcript

  1. Continuous Documentation - CI/CDύΠϓϥΠϯΛ׆༻ͨ͠จॻԽٕज़ - খࢁ݈Ұ࿠ / GMO PEPABO inc.

    2021.09.27 Pepabo Tech Conference #16 1
  2. 2 ࣗݾ঺հ ٕज़෦ɹٕज़ج൫νʔϜ 2018೥ த్ೖࣾ খࢁ ݈Ұ࿠ Ken’ichiro Oyama গ࣮͠༻తͰখ͞ͳOSSΛॻ͘ͷ͕झຯɻ

    ʢ࠷ۙྗΛೖΕ͍ͯΔOSS͸ https://github.com/k1LoW/octocov ͱ͍͏ओʹ GitHub ActionsͰಈ͔͢ίʔυϝτϦΫεϨϙʔτج൫ʣ • GitHub : k1LoW • Twitter : @k1LoW
  3. 3 ΞδΣϯμ 1. υΩϡϝϯτͱ͸ 2. γεςϜͱυΩϡϝϯτͷဃ཭ 3. γεςϜͱυΩϡϝϯτͷဃ཭Λͳ͘͢Ξϓϩʔν 4. ܧଓతυΩϡϝϯςʔγϣϯ

    5. ·ͱΊ
  4. “υΩϡϝϯτ”ͱ͸ 4

  5. 5 υΩϡϝϯτͱ͸ ։ൃ։࢝·ͰͷΦʔόʔϔου

  6. υΩϡϝϯτͱ͸ 6 ։ൃऀ͕ɺ஌ࣝθϩͷঢ়ଶ͔ΒγεςϜΛཧղ͠։ൃΛ։࢝͢Δ·Ͱͷ࣌ؒ΍ίετΛɺ ຊൃදͰ͸ʮ։ൃ։࢝·ͰͷΦʔόʔϔουʯͱݺͿʢʮΦϯϘʔσΟϯάͷίετʯͱ ͍ͬͨํ͕Ұൠత͔΋ʣ • ։ൃऀ͕γεςϜΛཧղ͍ͨ͠ͱ͖ • ։ൃऀ͕৽ͨʹγεςϜ։ൃʹࢀՃͨ͠ͱ͖ •

    ΋͘͠͸։ൃऀ͕ࣗ෼ͷ୲౰Ҏ֎ͷߏ੒ཁૉ΍ػೳΛཧղ͍ͨ͠ͱ͖ • γεςϜͰར༻͍ͯ͠Δٕज़ελοΫʹे෼ͳ஌ݟ͕͋ͬͨͱͯ͠΋ɺ࣮͸։ൃ։ ࢝·Ͱʹ͸खؒͱ͕͔͔࣌ؒΔ ։ൃ։࢝·ͰͷΦʔόʔϔου
  7. υΩϡϝϯτͱ͸ 7 ৽ن։ൃͷ৔߹ɺ࣮ࡍʹ։ൃΛ։࢝͢Δ·Ͱʹࠨ ਤʹ͋ΔΑ͏ͳෳ਺ͷϨΠϠʔʹ͍ͭͯݕ౼Λ͢ Δ • ๨ΕΒΕ͕͕ͪͩɺ్த͔Β։ൃʹJOIN͢ Δ৔߹΋ɺ৽ن։ൃ࣌ͱಉ͡਺ͷϨΠϠʔ ͷཧղ͕ඞཁʹͳΔ •

    ҧ͏ͷ͸ʮ͢Ͱʹ͋Δ΋ͷΛཧղ͢Δඞཁ ͕͋Δʯͱ͍͏͜ͱ͚ͩ ͲͷΑ͏ͳαʔϏε͔ ͲͷΑ͏ͳΞʔΩςΫνϟ͔ ͲͷΑ͏ʹσʔλΛอ࣋͢Δ͔ ʢʹͲͷΑ͏ͳςʔϒϧઃܭ͔ʣ ͲͷΑ͏ͳ։ൃ؀ڥ͔ ʢຊ൪؀ڥɾ։ൃ؀ڥʣ ͲͷΑ͏ͳίʔυ͔ ։ൃ αʔϏεཧղϨΠϠʔ ΞʔΩςΫνϟཧղϨΠϠʔ σʔλετΞཧղϨΠϠʔ ։ൃ؀ڥཧղϨΠϠʔ ίʔυཧղϨΠϠʔ ։ൃ։࢝·ͰͷΦʔόʔϔου
  8. 8 υΩϡϝϯτͱ͸ ։ൃऀ͕γεςϜΛཧղ͢Δ

  9. υΩϡϝϯτͱ͸ 9 • ৽͍͠։ൃऀ͸γεςϜΛݟͯཧղΛ͢Δඞཁ͕͋Δ • ։ൃ։࢝·ͰͷΦʔόʔϔου͕େ͖͍ঢ়ଶ γεςϜҎ֎ʹԿ΋ͳ͍ঢ়ଶ

  10. υΩϡϝϯτͱ͸ 10 • γεςϜͷཧղΛॿ͚ΔͨΊυΩϡϝϯτΛॻ͘ • ৽͍͠։ൃऀ͸υΩϡϝϯτΛ௨ͯ͡γεςϜͷཧղΛਐΊΔ͜ͱ͕Ͱ͖Δ υΩϡϝϯτͰཧղΛॿ͚Δ

  11. υΩϡϝϯτͱ͸ 11 • υΩϡϝϯτΛӡ༻͢Δ໨త → ։ൃ։࢝·ͰͷΦʔόʔϔουΛ࡟ݮ͢ΔͨΊ • ࡟ݮ͢ΔͨΊʹ͸γεςϜͷཧղΛॿ͚Δ͜ͱ͕Ͱ͖ͳ͍ͱ͍͚ͳ͍ • υΩϡϝϯτ͸͍ͭଘࡏ͢Δ΂͖͔

    → ཧղͯ͠΋Β͍͍ͨγεςϜ͕ଘࡏ͍ͯ͠Δͱ͖ • ܧଓతʹؒҧ͍ͷͳ͍े෼ͳυΩϡϝϯτ͕ଘࡏ͠ଓ͚Δඞཁ͕͋Δ • ※৽ن։ൃલͷʢઃܭͳͲͷʣυΩϡϝϯτ͸ຊൃදͷείʔϓ͔Β֎͢ ຊൃදʹ͓͚Δ”υΩϡϝϯτ" ʮܧଓతʹʯʮγεςϜͷཧղΛॿ͚ΔʯυΩϡϝϯτ͕ඞཁ
  12. γεςϜͱυΩϡϝϯτͷဃ཭ 12

  13. γεςϜͱυΩϡϝϯτͷဃ཭ 13 • γεςϜͱυΩϡϝϯτͱͷؒʹ಺༰ͷဃ཭͕ൃੜ͍ͯ͠Δ৔߹͕͋Δ • ʮॻ͍ͯ͋Δ͜ͱ͕ؒҧ͍ͬͯΔʯঢ়ଶʢ৔߹ʹΑͬͯ͸ʮॻ͍ͯ͋Δ͜ͱ͕ ଍Γͳ͍ʯ΋ʣ • ߃ৗతʹ಺༰ʹ͕ࠩग़͍ͯΔঢ়ଶ •

    ߋ৽λΠϛϯά͕ͣΕΔ͜ͱͰγεςϜͱυΩϡϝϯτͷ಺༰ʹ͕ࠩग़͍ͯΔঢ়ଶ γεςϜͱυΩϡϝϯτͷဃ཭
  14. γεςϜͱυΩϡϝϯτͷဃ཭ 14 • γεςϜͱͷဃ཭͕͋ΔυΩϡϝϯτͰγεςϜΛཧղ͢ΔͱɺؒҧͬͨཧղͰ։ൃ ʹೖͬͯ͠·͏ • ࣮͸ؔ࿈͕૿͍͑ͯͯؾܰʹ੾Γ཭ͤͳ͘ͳ͍ͬͯͨΠϯελϯε • ࣮͸ߟྀ͠ͳ͍ͱ͍͚ͳ͍͜ͱ͕มΘ͍ܾͬͯͨࡁػೳ •

    ࣮͸૿͍͑ͯͨόον • ։ൃऀ͕ͦͷဃ཭ʹؾͮ͘ͷ͕஗͚Ε͹஗͍΄Ͳ։ൃʹ͓͚ΔϚΠφε͕େ͖͘ͳΔ • γεςϜཧղͷ΍Γͳ͓͠🔥 • ίʔυͷॻ͖௚͠🔥 🔥 • ؒҧͬͨཧղͷ··ϦϦʔεɺޙʹো֐🔥 🔥 🔥 🔥 🔥 🔥 γεςϜͱυΩϡϝϯτͷဃ཭͕͋Δͱ
  15. γεςϜͱυΩϡϝϯτͷဃ཭ 15 γεςϜͱυΩϡϝϯτͷဃ཭Λখ͘͢͞ΔͨΊʹ͸ɺ·ͣɺγεςϜͱυΩϡϝϯτͷ ဃ཭Λ൑அͰ͖Δ࢓૊Έ͕ඞཁ • γεςϜͱυΩϡϝϯτͷରԠؔ܎Λද͢Ұछͷؔ਺͕ඞཁ • ʮͨͩυΩϡϝϯτΛॻ͘ʯγεςϜ͕ߋ৽͞Εͨͱ͖ʹɺυΩϡϝϯτͷͲ͜Λ ߋ৽͢Ε͹ྑ͍ͷ͔͕Θ͔Γʹ͍͘ˠͭ·Γؔ਺͕ͳ͍ঢ়ଶ ͦͯ͠ɺဃ཭͕͋ΔظؒΛͰ͖Δ͚ͩখ͘͢͞ΔͨΊʹ

    • ܧଓతʹ • Ͱ͖Δ͚ͩγεςϜͷߋ৽ʹ͍ۙλΠϛϯάͰ υΩϡϝϯτΛγεςϜʹ߹Θͤͯߋ৽͠ଓ͚Δ͜ͱ͕ඞཁ γεςϜͱυΩϡϝϯτͷဃ཭Λখ͘͢͞Δʹ͸
  16. γεςϜͱυΩϡϝϯτͷဃ཭ 16 γεςϜͱυΩϡϝϯτͷဃ཭ʹ͍ͭͯɺू߹࿦Λ༻͍ͯϞσϧԽ͢ΔࢼΈ γεςϜͱυΩϡϝϯτͷဃ཭ͷϞσϧԽ https://speakerdeck.com/k1low/web-system-architecture-number-8

  17. γεςϜͱυΩϡϝϯτͷ ဃ཭Λͳ͘͢Ξϓϩʔν 17

  18. 18 γεςϜͱυΩϡϝϯτͷဃ཭Λͳ͘͢Ξϓϩʔν γεςϜ͔Βߏ଄ԽσʔλΛநग़ͯ͠ υΩϡϝϯτੜ੒Λ͢Δ

  19. γεςϜͱυΩϡϝϯτͷဃ཭Λͳ͘͢Ξϓϩʔν 19 • JavadocɺgodocɺPHPDoc etc • γεςϜ͔ΒυΩϡϝϯτΛੜ੒͢Δ ͜ͱͰɺγεςϜͱυΩϡϝϯτͷဃ ཭Λͳͦ͘͏ͱ͍ͯ͠Δ γεςϜ͔Βߏ଄ԽσʔλΛநग़͢Δ

    υΩϡϝϯτ ߏ଄Խσʔλ γεςϜ
  20. γεςϜͱυΩϡϝϯτͷဃ཭Λͳ͘͢Ξϓϩʔν 20 • ຊൃදʹ͓͚ΔʮΞϊςʔγϣϯʯͱ͸ɺʮγεςϜʹର͢Δ։ൃऀͷཧղɾΠϝʔ δΛߏ଄Խσʔλʹϝλ৘ใͱͯ͠௥Ճ͢Δʯͱ͍͏ҙຯ • PHPDocͳͲͰ͸ɺίϝϯτΛιʔείʔυʹ • ιʔείʔυͷʮߏ଄ʹԊͬͨܗͰʯ •

    ͔ͭʮܾΊΒΕͨϑΥʔϚοτʹैͬͯʯ ௥Ճ͢Δ͜ͱͰɺॳΊͯ࠷ऴతͳυΩϡϝϯτʹ൓ө͞ΕΔ→Ξϊςʔγϣϯ ্هҎ֎ͷίϝϯτ͸υΩϡϝϯτ͔Β͸ແࢹ͞ΕΔ→ΞϊςʔγϣϯͰ͸ͳ͍ Ξϊςʔγϣϯ
  21. 21 γεςϜͱυΩϡϝϯτͷဃ཭Λͳ͘͢Ξϓϩʔν ߏ଄Խσʔλ͔Β γεςϜͱυΩϡϝϯτͷ྆ํΛੜ੒͢Δ

  22. γεςϜͱυΩϡϝϯτͷဃ཭Λͳ͘͢Ξϓϩʔν 22 • OpenAPI • ੜ੒ݩσʔλΛ1ͭʹ͢Δ͜ͱͰγε ςϜͱυΩϡϝϯτͷဃ཭Λͳͦ͘͏ ͱ͍ͯ͠Δ ߏ଄Խσʔλ͔ΒγεςϜͱυΩϡϝϯτͷ྆ํΛੜ੒͢Δ υΩϡϝϯτ

    ߏ଄Խσʔλ γεςϜ
  23. γεςϜͱυΩϡϝϯτͷဃ཭Λͳ͘͢Ξϓϩʔν 23 • 2ͭͷྫͷڞ௨఺ͱͯ͠ɺγεςϜͱυΩϡϝϯτͷؒʹߏ଄ԽσʔλΛհͨؔ͠࿈ Λ͍࣋ͬͯΔ͜ͱ͕Θ͔Δɻ • γεςϜͱυΩϡϝϯτͷରԠؔ܎Λද͢Ұछͷؔ਺ʹͳ͍ͬͯΔ 2ͭͷΞϓϩʔνͷڞ௨఺

  24. γεςϜͱυΩϡϝϯτͷဃ཭Λͳ͘͢Ξϓϩʔν 24 • γεςϜͱυΩϡϝϯτͷဃ཭Λͳͨ͘͢ΊʹɺγεςϜͷมԽͱ࿈ಈ͍ͯ͠Δߏ଄Խ σʔλΛυΩϡϝϯτੜ੒ʹ׆༻͢Δ • ʮγεςϜ͔Βߏ଄ԽσʔλΛநग़͢Δʯʮߏ଄Խσʔλ͔ΒγεςϜΛ࡞ΔʯͲͪ ΒͰ΋ྑ͍ • ιʔείʔυ΍ɺIaCͷίʔυͱ͍ͬͨίʔυ͚ͩͰͳ͘ɺ෼ࢄτϨʔγϯά΍Service

    DiscoveryɺService Mapͱ͍ͬͨ࢓૊ΈͰಘΒΕͨάϥϑ΋γεςϜͷมԽͱ࿈ಈͨ͠ߏ ଄Խσʔλͱݴ͑Δ • ߏ଄Խσʔλ͔ΒυΩϡϝϯτͷ਽ܗΛੜ੒͠ɺΞϊςʔγϣϯʹγεςϜͷཧղʹඞཁ ͳઆ໌Λ݀ຒΊ͍ͯ͘͠Πϝʔδ • ॏཁͳͷ͸Ξϊςʔγϣϯͷ݀ຒΊ·Ͱͯ͠ॳΊͯγεςϜͷཧղΛॿ͚ΔυΩϡϝ ϯτʹͳΔͱ͍͏͜ͱ ߏ଄ԽσʔλΛ׆༻ͨ͠υΩϡϝϯςʔγϣϯ
  25. ܧଓతυΩϡϝϯςʔγϣϯ 25

  26. ܧଓతυΩϡϝϯςʔγϣϯ 26 • γεςϜͱυΩϡϝϯτͷؒʹߏ଄ԽσʔλΛհͨؔ͠࿈Λ࣋ͨͤΔ͜ͱͰ྆ऀͷ ဃ཭Λͳ͘͢ख๏ʢʹπʔϧʣΛಘΔ͜ͱ͕Ͱ͖ͨ • ͦͷπʔϧΛ࣮ߦ͢Δͷ͕ɺৗʹ։ൃऀʹਓͰ͋Δͱʮ࣮ߦ๨Εʯ͕ൃੜͯ͠͠· ͏ • ΞϓϦέʔγϣϯͱಉ༷ʹɺCI/CDͷ࢓૊ΈΛ׆༻͢Δɻ

    • ηΩϡϦςΟ෼໺ʹ͓͚ΔDevSecOps΍ηΩϡϦςΟγϑτϨϑτɺDeveloper- First Securityͱಉ͡ ୭͕υΩϡϝϯςʔγϣϯπʔϧΛ࣮ߦ͢Δͷ͔ υΩϡϝϯτ΋ܧଓతʹσϦόϦ͢Δ
  27. 27 ܧଓతυΩϡϝϯςʔγϣϯ GMOϖύϘʹ͓͚Δ ܧଓతυΩϡϝϯςʔγϣϯ

  28. ܧଓతυΩϡϝϯςʔγϣϯ 28 σʔλϕʔεεΩʔϚͷ υΩϡϝϯςʔγϣϯ

  29. ܧଓతυΩϡϝϯςʔγϣϯ 29

  30. ܧଓతυΩϡϝϯςʔγϣϯ 30 • CIϑϨϯυϦͳσʔλϕʔευΩϡϝϯτੜ੒ πʔϧ • https://github.com/k1LoW/tbls • PostgreSQL, MySQLͳͲͷRDBMS͚ͩͰ

    ͳ͘ɺBigQuery΍Amazon DynamoDB, Cloud Spannerͱ͍ͬͨσʔλιʔεʹ΋ ରԠ • υΩϡϝϯτΛॆ࣮ͤ͞Δػೳͱͯ͠ϝλ σʔλΛΞϊςʔγϣϯ͢Δ͜ͱ͕Մೳ • ςʔϒϧɺΧϥϜͳͲͷίϝϯτ෇༩͚ͩ Ͱͳ͘λάɺϦϨʔγϣϯͳͲ tbls
  31. ܧଓతυΩϡϝϯςʔγϣϯ 31 • ैདྷ͸σʔλϕʔεͱυΩϡϝϯτ͸ ผͰ؅ཧ • CI্Ͱςετ༻σʔλϕʔε͔Β௚઀ ςʔϒϧఆٛΛߏ଄Խσʔλͱͯ͠ந ग़ɻͦΕʹ௥ՃͰςʔϒϧίϝϯτ΍ ΧϥϜίϝϯτΛΞϊςʔγϣϯ͠ɺ

    υΩϡϝϯτΛੜ੒ tbls
  32. ܧଓతυΩϡϝϯςʔγϣϯ 32 ΠϯϑϥΞʔΩςΫνϟͷ υΩϡϝϯςʔγϣϯ

  33. ܧଓతυΩϡϝϯςʔγϣϯ 33 ndiag

  34. ܧଓతυΩϡϝϯςʔγϣϯ 34 • https://github.com/k1LoW/ndiag • ओʹΠϯϑϥͷϋΠϨϕϧΞʔΩςΫ νϟͷυΩϡϝϯτΛੜ੒͢Δ໨తͰ։ ൃ • YAML͔Βʮߏ੒ਤΛੜ੒͢ΔʯͰ΋

    ʮυΩϡϝϯτΛੜ੒͢ΔʯͰ΋ͳ͘
 ʮෳ਺ͷ੾ΓޱͰߏ੒ਤΛؚΉΩϡϝϯ τͷ਽ܗΛ࡞Δʯͱ͍͏ಛ௃Λ࣋ͭ • ֤ߏ੒ཁૉ΍άϧʔϓʹΞϊςʔγϣϯ Λॻ͘͜ͱͰυΩϡϝϯτͱͯ͠੒ཱ͞ ͤΔ ndiag
  35. ܧଓతυΩϡϝϯςʔγϣϯ 35 • γεςϜͱυΩϡϝϯτͷؔ࿈෦෼͸ ʮߏ଄ԽσʔλΛநग़͢ΔʯͰ͸ͳ ͘ɺൺֱػೳ·Ͱ • ୯७ʹɺର৅ͱ͍ͯ͠ΔγεςϜ ͕ඇৗʹෳࡶͰ͔ͭଟذʹΘͨ ΔͨΊ

    • ౰વndiagͷೖྗ͸YAMLͳͷͰɺγε ςϜ͔Β৘ใΛߏ଄ԽσʔλΛநग़͢ ΔεΫϦϓτ͕࡞ΕΕ͹ɺͦΕΛ ndiagͷೖྗʹ͢Δ͜ͱ͕Մೳ ndiag
  36. ·ͱΊ 36

  37. ·ͱΊ 37 • ։ൃ։࢝·ͰͷΦʔόʔϔουͷ࡟ݮͷͨΊʹ͸ʮܧଓతʹʯʮγεςϜͷཧղΛ ॿ͚ΔʯυΩϡϝϯτ͕ඞཁ • ʮܧଓతʹɺؒҧ͍ͷͳ͍े෼ͳυΩϡϝϯτΛଘࡏ͠ଓ͚ͤ͞Δʯͱ͸ʮγες Ϝ͕มԽͯ͠΋γεςϜͱυΩϡϝϯτͷဃ཭Λେ͖͘͠ͳ͍ʯͱ͍͏͜ͱ • γεςϜͷมԽͱ࿈ಈͨ͠ߏ଄ԽσʔλΛ࢖ͬͯυΩϡϝϯτͷ਽ܗΛੜ੒͢Δ͜

    ͱͰɺγεςϜͷมԽ͕υΩϡϝϯτʹ൓ө͞ΕΔ࢓૊ΈΛߏஙͰ͖Δ • ্هͷ࢓૊ΈΛιϑτ΢ΣΞʹΑΓࣗಈԽɺ͞ΒʹCI/CDͷ࢓૊ΈʹࡌͤΔ͜ͱͰɺ γεςϜͱυΩϡϝϯτͷဃ཭ΛݶΓͳ͘ܧଓతʹখ͘͞อͭ͜ͱ͕ՄೳʹͳΔ ·ͱΊ
  38. ·ͱΊ 38 • γεςϜͷมԽͱ࿈ಈͨ͠ߏ଄ԽσʔλΛ࢖ͬͯυΩϡϝϯτͷ਽ܗ͸γεςϜͷมԽʹ ௥ै͢ΔΑ͏ʹͳͬͨɻ • ݱঢ়ɺͦΕΒʹ෇༩͢ΔΞϊςʔγϣϯʢ։ൃऀ͕ॻ͘આ໌จষʣΛͲ͏ܧଓతʹॻ͍ͯ ΋Β͏͔͕՝୊ • ΞϓϦέʔγϣϯͷιʔείʔυͱಉ͡Α͏ͳΞϓϩʔνͱͯ͠ɺΧόϨοδͷܭଌ

    ΍ΧόϨοδύʔηϯςʔδʹΑͬͯCIΛFailͤ͞Δ࢓૊ΈͳͲ͕ߟ͑ΒΕΔ • tbls΋ndiag΋υΩϡϝϯτͷΧόϨοδ͸ܭଌͰ͖ΔΑ͏ʹͳ͍ͬͯΔ • ΑΓϞνϕʔγϣϯΛ΋ͬͯॻ͍ͯ΋Β͏࢓૊Έ΍ɺΑΓॻ͖΍͘͢ͳΔ࢓૊Έ΋ߟ͑ͯ ͍͖͍ͨ • ࠶ܝ: ηΩϡϦςΟ෼໺ʹ͓͚ΔDevSecOps΍ηΩϡϦςΟγϑτϨϑτɺ Developer-First Securityͱಉ͡ ࠓޙͷ՝୊
  39. 39 Thank You! Thank You!