Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Documentation as Codeで継続的なドキュメント運用を実現する / July Tech Festa 2021 winter

Documentation as Codeで継続的なドキュメント運用を実現する / July Tech Festa 2021 winter

July Tech Festa 2021 winter [D-5]
https://techfesta.connpass.com/event/193966/

69b93af68320a590f607c296e8edff73?s=128

Ken’ichiro Oyama

January 24, 2021
Tweet

Transcript

  1. খࢁ݈Ұ࿠(.01FQBCP *OD +VMZ5FDI'FTUBXJOUFS %PDVNFOUBUJPOBT$PEFͰ ܧଓతͳυΩϡϝϯτӡ༻Λ ࣮ݱ͢Δ

  2. ϓϦϯγύϧΤϯδχΞ খࢁ݈Ұ࿠!L-P8 (.0ϖύϘϗεςΟϯάࣄۀ෦ϗεςΟϯάάϧʔϓ43&νʔϜ IUUQTHJUIVCDPNL-P8 

  3. 

  4. None
  5. ຊൃදʹ͓͚Δ lυΩϡϝϯτzͱ͸ 

  6. ։ൃ։࢝·ͰͷΦʔόʔϔου w ։ൃऀ͕৽ͨʹγεςϜ։ൃʹࢀՃͨ͠ͱͯ͠ɺͦͷ։ൃऀ͕γεςϜΛཧղͨ͠ ͍ͱ͖ w ΋͘͠͸։ൃऀ͕ࣗ෼ͷ୲౰Ҏ֎ͷߏ੒ཁૉ΍ػೳΛཧղ͍ͨ͠ͱ͖ w ஌ࣝθϩͷঢ়ଶ͔ΒγεςϜΛཧղ͠։ൃΛ։࢝͢Δ·Ͱͷ࣌ؒ΍ίετΛɺࢲ͸ ʮ։ൃ։࢝·ͰͷΦʔόʔϔουʯͱݺΜͰ͍ΔʢʮΦϯϘʔσΟϯάͷίετʯ ͱ͍ͬͨํ͕Ұൠత͔΋ʣ

    
  7. Կ΋ͳ͍ঢ়ଶ w ৽͍͠։ൃऀ͸γεςϜΛݟͯཧղΛ͢Δඞཁ͕͋Δ w ։ൃ։࢝·ͰͷΦʔόʔϔου͕େ͖͍ঢ়ଶ 

  8. υΩϡϝϯτ w γεςϜͷཧղΛॿ͚ΔͨΊυΩϡϝϯτΛॻ͘ w ৽͍͠։ൃऀ͸υΩϡϝϯτΛ௨ͯ͡γεςϜͷཧղΛਐΊΔ͜ͱ͕Ͱ͖Δ w ຊൃදͰ͸ʮγεςϜͷཧղΛॿ͚Δʹ։ൃ։࢝·ͰͷΦʔόʔϔουΛ࡟ݮ͢ ΔʯͨΊͷυΩϡϝϯτΛର৅ͱ͢Δ 

  9. γεςϜͱυΩϡϝϯτͷဃ཭ 

  10. γεςϜͱυΩϡϝϯτͷဃ཭ w γεςϜͱυΩϡϝϯτͱͷؒʹ಺༰ͷဃ཭͕ൃੜ͍ͯ͠Δ৔߹͕͋Δ w ߃ৗతʹ಺༰ʹ͕ࠩग़͍ͯΔঢ়ଶ w ߋ৽λΠϛϯά͕ͣΕΔ͜ͱͰγεςϜͱυΩϡϝϯτͷ಺༰ʹ͕ࠩग़͍ͯΔঢ় ଶ 

  11. γεςϜͱυΩϡϝϯτͷဃ཭Λখ͘͢͞Δʹ͸ γεςϜͱυΩϡϝϯτͷဃ཭͕͋Δ࣌ؒΛͰ͖Δ͚ͩখ͘͢͞ΔͨΊʹ͸ wܧଓతʹ wͰ͖Δ͚ͩγεςϜͷߋ৽ʹ͍ۙλΠϛϯάͰ υΩϡϝϯτΛߋ৽͠ଓ͚Δ͜ͱ͕ඞཁ 

  12. %PDVNFOUBUJPOBT$PEF 

  13. %PDVNFOUBUJPOBT$PEF %PDTBT$PEF SFGFSTUPBQIJMPTPQIZUIBUZPV TIPVMECFXSJUJOHEPDVNFOUBUJPOXJUIUIFTBNFUPPMTBTDPEF *TTVF5SBDLFST 7FSTJPO$POUSPM (JU  1MBJO5FYU.BSLVQ .BSLEPXO

    SF4USVDUVSFE5FYU "TDJJEPD  $PEF3FWJFXT "VUPNBUFE5FTUT 5IJTNFBOTGPMMPXJOHUIFTBNFXPSLqPXTBTEFWFMPQNFOUUFBNT BOE CFJOHJOUFHSBUFEJOUIFQSPEVDUUFBN*UFOBCMFTBDVMUVSFXIFSFXSJUFST BOEEFWFMPQFSTCPUIGFFMPXOFSTIJQPGEPDVNFOUBUJPO BOEXPSL UPHFUIFSUPNBLFJUBTHPPEBTQPTTJCMF IUUQTXXXXSJUFUIFEPDTPSHHVJEFEPDTBTDPEFɹΑΓൈਮɹ 
  14. %PDVNFOUBUJPOBT$PEF w γεςϜͷ։ൃͷ࢓૊Έͷۙ͘ʹυΩϡϝϯτ࡞੒ͷ࢓૊ΈΛஔ͘͜ͱͰγεςϜ ͱυΩϡϝϯτͷဃ཭Λͳͦ͘͏ͱ͍ͯ͠Δ͜ͱ͕Θ͔Δ w ຊൃදͰ͸ɺ·ͣɺ͜ͷʮ%PDVNFOUBUJPOBT$PEFʯ͔Β΋͏গ͠ʮγεςϜͱ υΩϡϝϯτͷဃ཭Λͳ͘͢ʯ͜ͱʹ౿ΈࠐΜͩΞϓϩʔνʹ͍ͭͯߟ͍͖͑ͯ· ͢ɻ 

  15. ϞσϧԽ ొ৔͢Δཁૉͱͯͭ͠  ։ൃऀ  γεςϜʜ։ൃऀ͕։ൃ΍ઃఆΛ͢Δର৅ɻΞϓϦɺσʔλϕʔεɺΠϯϑϥͳ ͲɻγεςϜࣗମ͸ߏ଄Խ͞Ε͍ͯΔʢ΋ͷΛର৅ͱ͢Δʣ  υΩϡϝϯτ 

    ߏ଄Խσʔλʜʮ:".-ʯ΍ʮϓϩάϥϜίʔυͷ"45ʯͳͲɻ ٯʹɺʮγεςϜʹର͢Δ։ൃऀͷཧղɾΠϝʔδʯ͸ෆఆܗͰ։ൃऀͦΕͧΕ ͕಄ͷதͰ͍࣋ͬͯΔ͚ͩͳͷͰߏ଄Խ͸͞Ε͍ͯΔͱ͸ݴ͑ͳ͍  ιϑτ΢ΣΞʜԿ͔͠ΒͷॲཧΛߦ͏ϓϩάϥϜɻߏ଄ԽσʔλΛೖग़ྗͱ͠ ΍͍͢ 
  16. υΩϡϝϯτΛॻ͘ w ʮͨͩυΩϡϝϯτΛॻ͘ʯ͸ʮγεςϜʹର͢Δ։ൃऀͷཧղɾΠϝʔδΛʢγ εςϜͷߏ଄ͱ͸ؔ܎ͳ͘ʣॻ͘ʯͱ͍͏͜ͱ w ಉ͡ߏ଄ʢ΋͘͠͸ؔ܎ੑͷ͋Δߏ଄ʣͰ͸ͳ͍৔߹ɺγεςϜ͕ߋ৽͞Εͨͱ͖ ʹɺൃੜͨ͠υΩϡϝϯτͱͷဃ཭ʢυΩϡϝϯτͷͲ͜Λߋ৽͢Ε͹ྑ͍͔ʣ͕ Θ͔Γʹ͍͘ 

  17. ʮγεςϜͱυΩϡϝϯτͷဃ཭Λͳ͘͢࢓ ૊ΈΛ࣋ͭ%PDVNFOUBUJPOBT$PEFʯ 

  18. γεςϜ͔Βߏ଄ԽσʔλΛநग़͢Δ 

  19. γεςϜ͔Βߏ଄ԽσʔλΛநग़͢Δ w +BWBEPDɺHPEPDɺ1)1%PDFUD w γεςϜ͔ΒυΩϡϝϯτΛੜ੒͢Δ͜ ͱͰɺγεςϜͱυΩϡϝϯτͷဃ཭Λ ͳͦ͘͏ͱ͍ͯ͠Δ w ʮߏ଄ԽσʔλʹܾΊΒΕͨϑΥʔϚο τͰʢυοΫίϝϯτΛʣΞϊςʔγϣ

    ϯ͍ͯ͠Δʯ͚ͩͳͷͰߏ଄Խσʔλͷ ··  ˞ ʮΞϊςʔγϣϯʯ͸ʮγεςϜʹର͢Δ։ൃऀͷཧղɾΠϝʔδΛ ߏ଄Խσʔλʹϝλ৘ใͱͯ͠௥Ճ͢Δʯͱ͍͏ҙຯ
  20. ߏ଄Խσʔλ͔ΒγεςϜͱυΩϡϝϯτͷ ྆ํΛੜ੒͢Δ 

  21. ߏ଄Խσʔλ͔ΒγεςϜͱυΩϡϝϯτͷ྆ํΛੜ੒͢Δ w 0QFO"1* w ੜ੒ݩσʔλΛͭʹ͢Δ͜ͱͰγες ϜͱυΩϡϝϯτͷဃ཭Λͳͦ͘͏ͱ͠ ͍ͯΔ 

  22. ͭͷΞϓϩʔνͷڞ௨఺ w ͭͷྫͷڞ௨఺ͱͯ͠ɺγεςϜͱυΩϡϝϯτͷؒʹߏ଄ԽσʔλΛհͨؔ͠ ࿈Λ͍࣋ͬͯΔ͜ͱ͕Θ͔Δɻ w ؔ࿈Λ࣋ͨͤΔ͜ͱ͕ɺײ֮తʹ͸ဃ཭Λগͳ͘͢Δ༗ޮͳखஈͱͳΓͦ͏ 

  23. *OGSBTUSVDUVSFBT$PEF w ྫ͑͹ɺ5FSSBGPSNΛಉ༷ͷϞσϧͰද͢ɻͱɺࣗͣͱυΩϡϝϯςʔγϣϯͷ࢓ ૊ΈΛೖΕΔ΂͖Օॴ͕Θ͔Δ 

  24. *OGSBTUSVDUVSFBT$PEF %PDVNFOUBUJPO w ͦͯ͠طʹ͜ͷϞσϧΛ࣮ݱͨ͠υΩϡϝϯςʔγϣϯπʔϧ͸͋Δ w IUUQTHJUIVCDPNUFSSBGPSNEPDTUFSSBGPSNEPDT 

  25. (.0ϖύϘʹ͓͚Δ ʮγεςϜͱυΩϡϝϯτͷဃ཭Λͳ͘͢࢓ ૊ΈΛ࣋ͭ%PDVNFOUBUJPOBT$PEFʯ ͷऔΓ૊Έ 

  26. σʔλϕʔεεΩʔϚͷ υΩϡϝϯςʔγϣϯ 

  27. 

  28. UCMT w $*ϑϨϯυϦͳσʔλϕʔευΩϡϝϯτੜ੒πʔϧ w IUUQTHJUIVCDPNL-P8UCMT w 1PTUHSF42- .Z42-ͳͲͷ3%#.4͚ͩͰͳ͘ɺ #JH2VFSZ΍"NB[PO%ZOBNP%# $MPVE4QBOOFS

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

    
  30. UCMTͷߏ଄Խσʔλͷ׆༻ w UCMTͷߏ଄Խσʔλͷ৘ใΛσʔλϕʔεʢ#JH2VFSZʣͷϝλσʔλʹ൓өͤ͞Δ w ৄ͘͠͸ผࢿྉʹͯ  IUUQTTQFBLFSEFDLDPNLMPXQFQBCPIBUFOB

  31. ʢΠϯϑϥʣΞʔΩςΫνϟͷ υΩϡϝϯςʔγϣϯ 

  32. ʮ։ൃ։࢝·ͰͷΦʔόʔϔουͷ࡟ݮ͢Δʯͱ͍͏໨త w Πϯϑϥͷ։ൃ։࢝·ͰͷΦʔόʔϔουΛ࡟ݮ͢Δʹ։ൃऀ͕Կ͔͠ΒΠϯϑϥ ͷमਖ਼΍τϥϒϧγϡʔτΛ։࢝͢ΔͨΊʹඞཁͳཧղΛॿ͚Δඞཁ͕͋Δɻ w ʮ͋Δϩʔϧͷϛυϧ΢ΣΞͷΞοϓσʔτΛ͢Δʯͱ͖ʹɺޮ཰Α҆͘શʹΞο ϓσʔτΛ։࢝͢ΔͨΊʹ࠷௿ݶԿͷཧղΛ͢Δ͔ w ର৅ͷϩʔϧͷ֓ཁ w

    ͦͷϩʔϧͱؔ܎ੑΛ࣋ͭϩʔϧͷ֓ཁ w ͦͷϩʔϧΛ࢖࣮ͬͯݱ͍ͯ͠Δػೳͷ֓ཁ w ܾͯ͠ΠϯϑϥશମͷཧղΛ͢ΔΘ͚Ͱ͸ͳ͍ɻ͔͠͠ɺγεςϜʹରͯ͠ҟͳΔ ੾ΓޱͰͷෳ਺ͷཧղʢʹυΩϡϝϯτʣ͕ඞཁ 
  33. υΩϡϝϯτʹىͦ͜͏ͱ͍ͯ͠Δ΋ͷϓϩδΣΫτ΍։ൃγεςϜͷશମ ૾͸ɺ۩ମతʹܗ͕͋Δ΋ͷͰ͸ͳ͘ɺͦΕͧΕͷ಄ͷதʹෆఆܗͳΠϝʔδͱ ͯ͠ଊ͑ΒΕ͍ͯΔͱࢥ͍·͢ɻ ෆఆܗͳΠϝʔδͷೝࣝΛ߹ΘͤΔͨΊʹࢲ͕ߟ͍͑ͯΔ͜ͱɺͦΕ͸ྠ੾Γʹ ͢Δ͜ͱͰ͢ɻ ྠ੾Γʹ͢Δͱ͖ʹ੾ͬͨ໘͕அ໘͕Ͱ͖ΔΘ͚Ͱ͕͢ɺ͜ͷஅ໘ΛੵΈॏͶͯ ͍͘ͱཱମͱͳΓɺશମ૾͕ݱΕ·͢ɻ ෆఆܗͳΠϝʔδΛڞ༗͢Δ͜ͱ͸೉͍͠ͱࢥ͍·͕͢ɺࣗ෼ͳΓʹஅ໘Λෳ਺ ࡞ΓɺͦΕΛੵΈॏͶ͍͚ͯ͹ࣗ෼ͳΓͷཱମΛཧղͯ͠΋Β͏͜ͱ͕Ͱ͖Δ͸ ͣͩͱߟ͑·͢ɻ

    ʮϚωδϝϯτۀΛ௨ͯ͡ߟ͑ͨɺϓϩδΣΫτશମ૾ͷೝࣝᴥᴪΛ๷͙ޡղ͞Εͳ͍υΩϡϝϯτ࡞੒ज़"/%1"%5FDI#MPHʯ IUUQTUFDIBOEQBEDPKQFOUSZΑΓൈਮɹ 
  34. OEJBH 

  35. OEJBH --- name: 3-Tier Architecture docPath: ../output diagrams: - name:

    overview layers: ["consul", "vip_group"] - name: http-lb layers: ["vip_group"] labels: ["http"] nodes: - name: lb-* components: - nginx?icon=lb-l7 clusters: - 'consul:dc1' - 'vip_group:lb' - name: app-* components: - nginx?icon=proxy - Rails?icon=cube4 clusters: - 'consul:dc1' - name: db-* components: - PostgreSQL?icon=db clusters: - 'consul:dc1' networks: - labels: - http route: 
  36. OEJBH w IUUQTHJUIVCDPNL-P8OEJBH w ʮΤψσΟΞάʯʮΤψμΠΞάʯͲͪΒͰ΋ ndiag doc -c ndiag.yml w

    ੜ੒͞ΕΔυΩϡϝϯτ͸(JU)VCʹίϛοτͯ͠8FC্͔ΒӾཡ͞ΕΔ͜ͱ૝ఆ w ओʹΠϯϑϥͷϋΠϨϕϧΞʔΩςΫνϟͷυΩϡϝϯτΛੜ੒͢Δ໨తͰ։ൃ w :".-͔Βʮߏ੒ਤΛੜ੒͢ΔʯͰ΋ʮυΩϡϝϯτΛੜ੒͢ΔʯͰ΋ͳ͘ ʮෳ਺ͷ੾ΓޱͰʯʮߏ੒ਤΛؚΉʯʮυΩϡϝϯτͷ਽ܗΛ࡞Δʯ ͱ͍͏ಛ௃Λ࣋ͭ 
  37. ʮෳ਺ͷ੾ΓޱͰʯ w ୯७ʹෳ਺ͷυΩϡϝϯτΛੜ੒ͯ͠͠·͏ͱɺγεςϜͷߏ଄ͱυΩϡϝϯτͷ ߏ଄ͷؔ܎͕ͳ͘ͳͬͯ͠·͍ɺγεςϜͱυΩϡϝϯτͷဃ཭͕ൃੜ͢Δ w ͦͷͨΊɺOEJBHͰ͸ҎԼͷΞϓϩʔνͰγεςϜͱυΩϡϝϯτͷߏ଄Խσʔλ Λհͨؔ͠܎ੑ͕੾Εͳ͍Α͏ʹ͍ͯ͠Δ w ͭͷߏ଄Խσʔλ͔Β੾ΓޱͷҟͳΔෳ਺ͷߏ଄ԽσʔλΛϧʔϧʹԊͬͯੜ੒ ͠ɺͦΕΒ͔ΒͦΕͧΕਤͱυΩϡϝϯτΛੜ੒͢Δ

    w ߏ଄ԽσʔλͱγεςϜͱΛൺֱݕূͰ͖Δ࢓૊ΈΛఏڙ͢Δ 
  38. OEJBHͷϞσϧ 

  39. ʮߏ੒ਤΛؚΉʯ  w ΠϯϑϥͷΞʔΩςΫνϟΛཧղ͢ΔͨΊͷ υΩϡϝϯτΛੜ੒͢Δʹ౰ͨͬͯਤ͸ॏཁ ͳཁૉɻੜ੒͞ΕΔਤͷݟ΍͢͞΋ॏཁ w ͦͷͨΊOEJBH͸ਤʹ࢖༻Ͱ͖ΔΞΠίϯ΋ ͍Ζ͍Ζબ୒Ͱ͖Δ w

    ૊ΈࠐΈΞΠίϯϑϨʔϜϫʔΫ w ೚ҙͷը૾ʢQOHTWHʣ w ,T"84($1)BTIJDPSQ͕ఏڙ͍ͯ͠ ΔΞΠίϯηοτΛऔಘ͢ΔίϚϯυ
  40. ʮυΩϡϝϯτͷ਽ܗΛ࡞Δʯ w υΩϡϝϯτͷੜ੒ݩ͸ߏ଄ԽσʔλͰ͋Δ΄͏͕γεςϜͱͷဃ཭Λখ͘͞͠΍ ͘͢Ͱ͖Δͱ͍͏ͷ͸ຊൃදͰड़΂ͨͱ͓Γɻ w OEJBH΋Πϯϑϥͷ֤ཁૉͷઆ໌จষ௥Ճ͸ʮΞϊςʔγϣϯʯͷܗͰ࣮ݱɻ w ͭ·ΓOEJBH͸ߏ଄Խσʔλ͔ΒυΩϡϝϯτΛੜ੒͢Δ w ͔͠͠ɺઆ໌จষ͸ςʔϒϧίϝϯτͱ͸ҟͳΓ௕จʹͳΔ͜ͱ͕༧૝͞ΕͨͷͰ

    ҎԼͷํࣜΛ࠾༻  ·ͣOEJBHଆͰઆ໌จষهड़ઐ༻ͷϑΝΠϧΛॴఆͷҐஔʹੜ੒  ։ൃऀ͸ͦͷઐ༻ϑΝΠϧʹઆ໌จষΛهड़  OEJBH͸υΩϡϝϯτੜ੒࣌ʹઐ༻ϑΝΠϧͷ಺༰ΛऔΓࠐΉ 
  41. (.0ϖύϘʹ͓͚ΔOEJBHಋೖঢ়گ w ϖύϘ͕ӡ༻͍ͯ͠Δෳ਺ͷαʔϏεͷ͏ͪͷҰ෦ͰΞʔΩςΫνϟυΩϡϝϯτ Λ࡞੒͢Δͷʹར༻ͯ͠΋Β͍ͬͯΔ w ͔ͦ͜Β༷ʑͳϑΟʔυόοΫΛ΋Βͬͯػೳ௥ՃΛ͍ͯ͠Δ w ࣮͸OEJBHࣗମ͸·ͩ3&"%.&NEΛؚΉυΩϡϝϯτΛ੔උͰ͖͍ͯͳ͍ w ࣾ಺Ͱ͸࣌ؒఔ౓ͷϋϯζΦϯΛ։࠵࣮͠ࡍʹಈ͔ͯ͠΋Βͬͯཧղͯ͠΋Βͬ

    ͍ͯΔ 
  42. ·ͱΊ 

  43. ·ͱΊ w ։ൃ։࢝·ͰͷΦʔόʔϔουΛ࡟ݮ͢ΔυΩϡϝϯτΛܧଓతʹӡ༻͍ͯͨ͘͠ Ίʹɺʮ%PDVNFOUBUJPOBT$PEFʯΛجຊͱ͠ͳ͕Β΋ɺͲͷΑ͏ͳ࢓૊ΈΛ࡞ͬ ͍ͯ͘ͱγεςϜͱυΩϡϝϯτͷဃ཭Λখ͘͞Ͱ͖Δ͔ΛϞσϧΛ࢖ͬͯઆ໌͠ ͨɻʮγεςϜͱυΩϡϝϯτΛߏ଄ԽσʔλΛհͯؔ͠࿈ͤ͞Δʯ͜ͱ͕ॏཁɻ w (.0ϖύϘͰͷऔΓ૊Έͱͯ͠ྫΛ঺հͨ͠ɻ w 5CMTΛ։ൃ͠ɺߏ଄ԽσʔλΛத৺ʹਾ͑ͯߟ͑Δ͜ͱͰσʔλϕʔευΩϡϝ

    ϯτ͚ͩͰͳ͘σʔλج൫ͷϝλσʔλ؅ཧͷ࢓૊Έ·Ͱ࣮ݱͨ͠ɻ w γεςϜͷཧղͷͨΊʹ͸ෳ਺ͷ੾ΓޱͰͷυΩϡϝϯτ͕ඞཁͰ͋ΓɺͦΕΛ αϙʔτ͢ΔͨΊͷυΩϡϝϯςʔγϣϯπʔϧͱͯ͠OEJBHΛ։ൃ͍ͯ͠Δɻ 
  44. 5IBOLZPV ࠷৽ͷ࠾༻৘ใΛνΣοΫˠ !QC@SFDSVJU