nais developer documentation
Home Page: https://doc.nais.io
License: MIT License
See the NAIS handbook for a more detailed explanation of the documentation structure and how to contribute.
asdf plugin add poetry
asdf install poetry latestmake installmake localmake local tenant=nav
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
Har nylig prøvd å installere Linux (Ubuntu 20.04 LTS) ved å følge dokumentasjonen på https://doc.nais.io/device/install/ Det ser ut til å fungere fint - har ikke rukket å ta den nye laptopen i bruk i skrivende stund - men: Det tok lang tid fra Kolide rapporterte at alt var ok til naisdevice appen ble grønn (ikonet var gult). Vet ikke hvor lang tid, men helt sikkert mer enn fire timer (installerte på ettermiddage og sjekket sent på kvelden igjen). Jeg lot laptopen stå på over natta, og morgenen etter fikk jeg koblet på naisdevice-appen ok.
Jeg kommuniserte litt med Christian Chavez rundt dette: https://nav-it.slack.com/archives/C013XV66XHB/p1619532481122900
Etter at vi innførte team namespaces så er informasjonen på https://doc.nais.io/deployment/change-team mangelfull.
Vi må oppdatere med hva som trengs for å flytte en app fra et namespace til et annet.
Forrige uke var jeg i et møte hvor det ble etterlyst hva slags forventninger NAIS hadde til applikasjoner som kjører, og hva de kan forvente av oss. Prøvde å se igjennom doc-en vår, men fant ikke så mye. Det eneste jeg klarte å finne var her: https://github.com/nais/doc/blob/master/nais-application/README.md
Tenkte derfor å lage et issue som en start på en enkel tekst med forventninger vi har, og hva slags spørsmål jeg har fått. Fint hvis andre hiver inn sine egne forventninger og spørsmål.
Spørsmål jeg har fått:
Ønsker meg litt hjelp på https://github.com/nais/doc/blob/master/observability/metrics.md som kan si noe om når jeg bør bruke Prometheus, når jeg bør bruke Sensu+Influx og når jeg bør bruke "vanlig" logging a la slf4J+Logback+Kibana
Det står ikke noe om det her https://doc.nais.io/observability/alerts/spec#spec-receivers-slack-channel
og nå som vi sliter med at vi ikke får alerts fra vår nye app leter vi med lys og lykter etter hva som kan være feil.
Hey there Chainguard here.
We noticed that you are using Chainguard Images, thank you! We wanted to make you aware of an upcoming change that will impact your project.
Starting August 16, 2023 public users will no longer be able to pull images from our registry (cgr.dev/chainguard) by tags other than latest or latest-dev. Please see the announcement for more information.
You are currently using the following.
In https://github.com/nais/doc/blob/c1baa8df3aa4d1d2ea5415b2233b95315c35eace/docs/guides/basics.md:
Our goal is to prevent your project from experiencing any disruptions. Please see the migration guide for options.
If there's more we can do to help please reply to this issue or email us at [email protected].
Thank you!
Two persons for one week.
We have two challenges with the current documentation:
<tenant> in the documentation to make the documentation generic.nais is a platform with a lot of features and history. Much of what we provide is not (yet) relevant for all tenants through our naas offering. This is a problem because it makes it harder to find the relevant documentation and for tenants to understand what they can use and if there are any limitations specific to their tenant.
Since we are using placeholders in the documentation, it is not possible to link to tenant specific resources. This is a problem because it makes it harder to access the correct resource and a majority of our users are not aware of what their tenant is called (this is primarily an issue within nav).
Some links and names are not using placeholders and are hard-coded to a specific tenant (nav in most cases).
We can use the mkdocs-macros-plugin to create a macro that will only render a section of the documentation if the tenant is in the list of tenants that should see the section. We can also use propper tenant names instead of the <tenant> placeholder when linking to relevant tenant specific resource.
mkdocs-macros-plugin is a plugin for mkdocs that allows us to create variables and macros by leveraging the jinja2 templating language. It is installed as a plugin in the mkdocs.yml file like this:
plugins:
…
- macrosThen we can build the documentation for each tenant and publish it to a tenant specific url, e.g. https://docs.<tenant>.cloud.nais.io and keeping https://docs.nais.io as the default documentation for nav. When this is enabled, we can remove the <tenant> placeholder from the documentation and replace it with the correct tenant name like this:
This is the documentation for the {{ tenant_name }} tenant.This will render as this for the nav tenant:
This is the documentation for the nav tenant.Jeg fant ikke noe dokumentasjon for å bruke python med maskin porten. Fant ingen repo på git hub heller i python.
Folk etterlyser konkrete eksempler på hvordan man skal sette opp en app og pipeline. Dette er et vidt problem, med mange løsninger, og jeg tro vi bare må begynne i en ende.
Kjør gjerne diskusjon på hvordan vi kan dokumentere dette.
Most saksbehandler-applications (and similar) need to audit log. How to do this is currently a bit hidden, but documentation exists at https://github.com/navikt/naudit. I suggest adding a short section about audit logging on the log page, refering to the naudit-repo for details.
Skulle ønske dokumentasjonen på https://doc.nais.io/observability/alerts/spec#spec-alerts inneholdt de gyldige verdiene jeg kan bruke for spec.alerts[].severity og spec.alerts[].for
(Forøvrig er navnet "for" ikke så beskrivende. Hva med "wait" eller "endure" eller "tolerate", ev. postfixet med "-duration"? Jeg kan leve med det som det er, det koster sikkert mer enn det smaker å endre på.)
Her https://github.com/nais/doc/blob/master/content/getting-started/vdi.md står det "Since we are running our Windows VDI with virtualisation off, we need to have the Docker daemon running on an external Linux-server or VDI ..."
Men her https://confluence.adeo.no/display/TEAMARENA/Windows+10+Arena+utviklerimage+-+Tillegg+for+NAIS-utvikling#Windows10Arenautviklerimage-TilleggforNAIS-utvikling-Enablevirtualiseringiimaget står det
"Virtualisering må være enablet for å kunne kjøre Docker for Windows i imaget. Bestilles i Slack-kanalen #tech-virualisering."
Jeg har nylig gjort det siste - fordi det var den dokumentasjonen jeg tilfeldigvis fant først - og det funket.
The recommended alert:
Using this example for our app like this:
up{app="skjemautfylling", namespace="skjemadigitalisering"} == 0
generates many alerts in our slack channel. On fiddling with this expr and sub exprs in prometheus indicates that the query will succeed if ANY pod that matches the criteria goes down. This happens every time we deploy since the old pods will go down and therefore be 0 instead of 1.
Replacing the query with:
sum(up{app="skjemautfylling", namespace="skjemadigitalisering"}) < 2
seems to work better. (Where 2 is the number of pods you expect to be always up)
Avsnittet Acces from Laptop - Google Cloud Platform (GCP)" - bør ha lenke til GCP - Getting Started - Acess for å fortelle hvordan det opprettes og gis tilgang til teams.
Kontrasten til lenker, titler/ikoner og bakgrunnen i darkmode har en kontrast på rundt 3:1, og bryter derfor med WCAG sitt minimumskrav om kontrast på 4.5:1. Legger ved før-etter bilder der kontrasten på nevnte elementer er hevet til 7:1, som er det anbefalte kontrast-nivået.
Gjøre det tydeligere i dokumentasjonen om hva som er anbefalt for produksjonsbruk.
Informere i announcements om oppdatering av dokumentasjon.
Lage et dashboard som viser hvordan det utvikler seg.
Gjelder instruks for oppsett av secure log på https://doc.nais.io/observability/logs/#2-connect-the-ad-group-to-your-team-in-kibana
The easiest way to achieve this is to ask in the #atom slack channel. And ask them to connect AD-group X to team Y.
Hva menes med team her? Er det Github-teamet? Er det AD-gruppen til teamet? Er det bare en oppramsing av Nav-brukernavn på utviklere?
Docker er en vital del av alles hverdag, men ikke nevnt i stor grad i dokumentasjonen vår. Finne et passende sted å dokumentere bruken vår av Docker, og lenke til relevant dokumentasjon. Kan også nevne at det er fullt mulig å bruke noe annet enn Docker, så lenge man kan tilby et Docker-image.
Dokumentasjonen vår kunne hatt godt av noen tegninger og beskrivelse på hva som skjer når du lager en application-ressurs, og hva en sånn ressurs er for noe.
I anbefalte alerts i https://github.com/nais/doc/blob/master/observability/alerts/recommended_alerts.md er det en alert "høy feilrate for http-requester". Den bruker Jetty. Default for Spring Boot er Tomcat. Ønsker meg et eksempel på hvordan jeg får samme alert for Tomcat. Fordi jeg sliter skikkelig med å finne det ut selv.
Heisann,
Jeg er jo nyansatt her, og har brukt anledningen til å gå over dokumentasjonen med "ferske øyne".
Spørsmålet jeg kunne ønske meg å drøfte med resten er om jeg har gått glipp av noe resonnement/tankegang bak hvorfor å kalle den ene seksjonen for clusters?
Inputs, noen?
Flere har etterspurt en samleside som innholder linker til dok for hvordan opprette de ulike applikasjonsressursene.
For eksempel: AAD application, vault, database, servicebrukere etc.
Vi trenger en liten forklaring på hva de forskjellige container-verktøyene er, og hvorfor det er så mange. Noen hadde også testet Colima, men ikke skjønt hvordan det hang sammen med Docker Desktop. Så her kan vi nok med noen få linjer gjøre det enklere for brukerne å bruke Colima i stedet for at vi skal kjøpe lisens til Docker Desktop.
Docen anbefaler å lage alerts på metrikker som ikke eksisterer i nginx.
Vi bør derfor se over hvilke alerts vi anbefaler slik at kart stemmer med terreng.
https://doc.nais.io/observability/alerts/recommended_alerts/ er per skrivende stund kun mulig å bruke onprem da den bruker metrikker fra traefik
(I'm sorry this issue is written in Norwegian, but it's generated by a script meant for the navikt organisation. Use Google Translate if you want to know what is written)
Dette er en autogenerert issue, laget av et skript som går gjennom alle NAV sine kodebaser på Github og gjør diverse sjekker. Her er en liste over ting som kan endres for at kodebasen skal bli enda bedre!
Alle kodebasene til NAV skal (i utgangspunktet) lisensieres med MIT-lisens.
Bruk den lisensen her: https://github.com/navikt/utvikling/blob/master/LISENSIERING.md
Dette er en fil som skal ligge i rotkatalogen, og angir hvilket team som eier kodebasen, på et maskinlesbart format. Den enkleste varianten, som vil holde for de fleste, er å ha en CODEOWNERS-fil som ser slik ut: (Merk at det skal være asterisk/stjerne foran navn på teamet!)
* @nais/teamnavn
Gyldige teamnavn på Github er:
@nais/aura (aura)@nais/bots (bots)Her er en oppdatert liste over team i Github.
Mangler teamet deres i lista? Ta kontakt med noen i Core-teamet på Github, så kan de opprette et team til dere.
Hvis det trengs spesielle tilpasninger, så ligger det mer dokumentasjon om CODEOWNERS-filformatet her:
https://help.github.com/articles/about-codeowners/
Ikke alle er enig i at merge commits skaper støy i git-loggen. Så dette er valgfritt. Men for de som synes det, så er det mulig å slå på en funksjon slik at alle pull requests gjøres med rebase i stedet for merge - da får man en renere git-logg.
For å endre dette, går man inn på Settings-panelet til Github-repoet, under avsnittet "Merge button" og slår av "Allow merge commits".
Hvem som helst (av utviklerne i NAV) kan pushe til master-branchen i denne kodebasen. Det kan åpne opp for sårbarheter. For det første vil det en gang i blant skje uhell - utviklere commiter og pusher til en branch for å lage pull request, men så pusher de ved et uhell rett til master-branchen. Det åpner også opp for at noen som har tatt kontroll over en utviklerkonto på Github (eller en utro tjener) kan pushe kode rett til master-branchen og deploye direkte til produksjon, på egen hånd. (Kall det gjerne spekulativt, men det er en mulighet.)
Hvis man ønsker å gjøre noe med det, kan man gå i Settings-panelet til Github-repoet, velge "Branches", og under "Protected branches" sette opp master som protected.
Det er vel opp til teamet å bestemme selv nøyaktig hva kriteriene for push/merge til master skal være, men her kan man for eksempel legge inn krav om grønt bygg før merge, og/eller man kan kreve at koden må ha vært godkjent i code review av minst x antall utviklere fra teamet som eier kodebasen. Man kan også konfigurere at kun medlemmer av teamet som eier koden skal kunne merge pull requests.
Skriv i vei, på Slack-kanalen #open-source.
Selv om koden i dag ikke er åpen for innsyn, så ta høyde for at den kan komme til å bli det i fremtiden. Uansett så vil forbedringene være til hjelp, enten kodebasen er åpen eller ei!
Det er i utgangspunktet den/de/teamet som eier kodebasen som må gå gjennom.
Ikke egentlig. Men det hadde vært fint om det ble gjort, innen et par uker kanskje?
Det er greit. Bare skriv "kan dere gjøre det for oss?" som svar på denne issuen. Så kan vi gå gjennom sakene senere med et annet skript, og gjøre endringene automatisk!
Foreslår at dokumentasjonen om alerts får et eget kapittel om hvordan lage én alerts-fil som kan brukes av mange apper. Jeg tror det er dette leseren er ut etter når hen kommer til denne delen av Nais-doc-en, og/eller det er dette doc-en bør anbefale/lede folk til å lage.
Per i dag har doc-en noen tekniske detaljer om hvordan man kan bruke labels https://doc.nais.io/observability/alerts/index.html#expressive-descriptions-or-actions og teste spørringer i Prometheus, men det er ikke nok til å "ta meg i mål". Det henvises til doc-en til Prometheus og Kibana, som igjen er veldig tenkisk. Doc-en som den er nå er "bare-bones". For meg som bruker av do-en hadde det vært bedre at de tekniske detaljene var beskrevet mer i kontekst av hva det bør brukes til og hvordan, med eksempler. Eksempler er gull.
Denne issuen er en ryddigere versjon av det jeg kavet med her
It came up in a discussion between @x10an14, @Kyrremann, @gorzan, and I, that it seems reasonable to split documentation regarding on-prem and GCP in separate parts.
First and foremost, this would help tidy up the connections between different parts of NAIS (at least, when it comes to GCP and on-prem 🙃 ) as certain things specific to one or the other currently have their most natural location in other categories. Thus, the current setup can be a little bewildering since one might see a thing in another category and think "hey, that's a cool technology!" only to find it is only supported in a Kubernetes cluster that the reader isn't using.
I'm certain there are problem spots with this kind of setup, since the two kinds of clusters share a fair bit of info. It might lead to needing some duplicate info between the two categories, or a third main category that collects the shared stuff, neither of these are particularly desirable ideas.
Still, I do feel as if it could be beneficial for the reader if this is done with care.
Dette er en autogenerert issue, laget av et skript som går gjennom alle NAV sine kodebaser på Github og gjør diverse sjekker. Her er en liste over ting som kan endres for at kodebasen skal bli enda bedre!
Skriv i vei, på Slack-kanalen #open-source.
Selv om koden i dag ikke er åpen for innsyn, så ta høyde for at den kan komme til å bli det i fremtiden. Uansett så vil forbedringene være til hjelp, enten kodebasen er åpen eller ei!
Det er i utgangspunktet den/de/teamet som eier kodebasen som må gå gjennom.
Ikke egentlig. Men det hadde vært fint om det ble gjort, innen et par uker kanskje?
Det er greit. Bare skriv "kan dere gjøre det for oss?" som svar på denne issuen. Så kan vi gå gjennom sakene senere med et annet skript, og gjøre endringene automatisk!
Det står ingenting om at naisjobber som kjører i gcp følger utc tidssone. Det er for noen åpenbart at alt som kjører på servere som følger utc har en påvirkning på schedulert cronjobber, men for andre er det mindre åpenbart. Det ønskes å legge til spesifikk informasjon om itdssoner relatert til Naisjobber.
https://doc.nais.io/cli/commands/aiven/#aiven-command
Flisespikking, men på windows har man ikke /tmp mappen.
Input fra team Bømlo
https://doc.nais.io/persistence/postgres/#granting-temporary-personal-access beskriver hvordan man setter opp en admin-bruker ("grant all") - det hadde kanskje vært bedre å "defaulte" til å sette opp les-tilgang, og at admin-tilgang blir beskrevet som en mulighet?
Informasjonen i on-premises.md (https://doc.nais.io/clusters/on-premises/) om ingresser/domener ser bra ut, men det kan kanskje tydeliggjøres at intern.nav.no også kan nås fra vdi? "accessible from"-kolonnen sier bare naisdevice.
Om man søker etter x_ i søkefeltet, så dukker det ikke opp noe relevant dokumentasjon.
Ref logging, og at dette er et prefix som settes på "ikke-gjenkjente" felter.
Hvordan deployment-cli fungerer er litt kryptisk. Trenger en bedre oversikt over flagg som er nyttige for folk flest.
https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/
Dette kan hjelpe på discoverability
Jeg fant https://doc.nais.io/cli/commands/postgres/#users-add men jeg klarer ikke å forfatte en kommando som gir meg rettigheter til å kjøre en insert i Postgres tabellen min (som jeg kan kjøre select på). Et eksempel på en slikkommando i dokumentasjonen hadde vært gull.
https://doc.nais.io/in-depth/nais-manifest har en tabell som er veldig bred. Se på andre løsninger for å vise innholdet.
@ThomasKasene foreslår:
Metadata:
Parameter Required Description
name x ...
Må bare sørge for å synliggjøre at metadata: må være med
doc/docs/nais-application/access-policy.md
Line 121 in 6a26f29
Kunne vært kjekt med en enkel opplisting av verktøy som vi bruker og anbefaler. Gjerne med en kort beskrivelse og lenke til nyttig dokumentasjon (både intern og ekstern).
Er det noe flere?
Ser ikke noe eksempel for python kode i dokumentasjon. Prøver å forberede for onboarding. Jeg prøvde selv å bruke python men deploy feiler hver gang.
Død lenke på https://github.com/nais/doc/blob/master/observability/metrics.md i setningen "Remember to format the data as Influxdb syntax."
Prøvde å følge doc'en for deployment, men fikk det ikke til, og sitter igjen med en del sprøsmål. Lister de opp nedenfor, så de ikke går i glemmeboken.
din ip x.x.x. har ikke tilgang...Kan sees på i sammenheng med #179
Jeg skulle ønske at dokumentasjonen om alerts https://doc.nais.io/observability/alerts/#expressive-descriptions-or-actions forklarte bedre hvordan jeg kan vite hvilke labels jeg har tilgjengelig. Jeg ser hvordan jeg kan referere til en label, men hvordan vet jeg om en label eksisterer? Hvor kommer labels fra?
Grunnen til at jeg begynte å tenke på dette er at mitt team har hatt alerts i Slack hvor det ikke står hvilken app som er opphavet til alerten. Det ble slik fordi alerten hadde severity warning, og vi hadde basert oss på å bruke prependText https://doc.nais.io/observability/alerts/reference/#receiversslackprependtext til å hardkode appnavnet der. Jeg oppdaget da at prependText bare brukes for alerts med severity danger.
Vi hadde definert en alert som var definert med action: "Sjekk loggene til app {{ $labels.log_app }} i namespace {{ $labels.log_namespace }}, for å se hvorfor det forekommer warnings".
Da denne førte til en melding i Slack sto det ingenting istedenfor {{ $labels.log_app }} og {{ $labels.log_namespace }}
With the introduction of a documentation stack that allows for more fine grained control, I think it would be quite useful to add some sort of analytics tool (I suppose there was already support for this in GitBooks too? I don't know). I'm especially thinking about the case that page views can be counted; with such data can work be done to put the more viewed pages closer to the reader and thus (hopefully) improve the quality of life for those who wish to read the more important pages.
There exists documentation on how to set up analytics where the path of least resistance is certainly Google Analytics, though there's also a set of instructions on how one would implement alternative services (I'm thinking Amplitude, since there exists some organisational license).
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
Django
The Web framework for perfectionists with deadlines.
Laravel
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft
Open source projects and samples from Microsoft.
Google
Google ❤️ Open Source for everyone.
Alibaba
Alibaba Open Source for everyone
D3
Data-Driven Documents codes.
Tencent
China tencent open source team.