středa 18. července 2018

React a hrátky s TypeScriptem


V minulosti jsem se již několikrát zmiňoval, že používat JavaScript bez statických typů, je stejné jako jezdit na kole poslepu. Nemusí se Vám nic stát, ale také si můžete hezky ublížit. Jednou z variant, jak částečně předcházet problémům, je použití staticky typovaného jazyka. Už během psaní kódu je více viditelné, že "něco není v pořádku". TypeScript (dále jen TS) je jazyk, který nám k tomuto účelu může dobře posloužit.

Cílem dnešního článku jsou příklady, na kterých se pokusím demonstrovat vlastnosti jazyka, se kterými se lze setkat. Výčet určitě není kompletní, protože TS je velice sofistikovaný jazyk, který se nedá popsat ani jednou knihou.

Generické typy


Jak jednou řekl můj bývalý kolega: "Generické typy? To je ten zápis s kachníma zobákama, ne?" :)

Generické typy jsou součástí snad každého staticky typovaného jazyka. Generiky naleznete jak v Jave, C#, tak právě i v TS. Pokud v TS píšete, tak neexistuje téměř možnost, že byste se s generickými typy nesetkali.

Pojďme se podívat na jednoduchý příklad:
interface Props {
    firstName: string;
    lastName: string;
}
const User: React.SFC<Props> = ({firstName, lastName}) => (
    <div>
        {firstName} {lastName}
    </div>
);
const App = () => <User firstName={'Ales'} lastName={'Dostal'} />;

Zde je vidět, že je použita generika v React.SFC, což je typ, který definuje, že se jedna o React Stateless komponentu. Součástí tohoto typu je možnost uvést generický typ, tedy předem neznámý typ, který ovšem po deklaraci, bude kontrolován.

Zjednodušeně se dá říci, že pokud bychom v komponentě User definovali neznámý atribut, bude nám TS hlásit chybu:
Chybný atribut foo 
Jejich využití má největší přidanou hodnotu ve chvíli, kdy píšete kód, který má využití na více místech. Generické typy nabízí právě tu možnost, aby daný kód byl co nejvíce variabilní.

Od verze TS 2.9 je možné generické typy používat i přímo v JSX. Díky tomu je například snadnější typovat render props v Reactu.

Enum a string literal types


Často se dostáváme do situací, kdy je třeba definovat přesný výčet hodnot, které lze použít. 

Pojďme si rozšířit naší komponentu o novou vlastnost:
type UserType = 'admin' | 'guest';

interface Props {
    firstName: string;
    lastName: string;
    type: UserType;
}

const User: React.SFC<Props> = ({firstName, lastName}) => (
    <div>
        {firstName} {lastName}
    </div>
);
const App = () => <User firstName={'Ales'} lastName={'Dostal'} type={'admin'} />;

Nyní jsme přidali typ uživatele. Tím typem může být administrátor či host.

Pokud bychom do atributu type vložili jiný typ, tak TS zahlásí chybu:
Chybný typ uživatele
Kromě možnosti definovat výčet pomocí string literal types, tak je možné onen typ definovat i pomocí enum.

Příklad:
enum UserType {
    ADMIN = 'admin',
    GUEST = 'guest',
}
const App = () => <User firstName={'Ales'} lastName={'Dostal'} type={UserType.ADMIN} />;


Type queries a typeof


JavaScript disponuje klíčovým slovem typeof, který umí číst typy z jakéhokoliv objektu. Velice efektivně toho dá využít pro pro vytvoření typu z objektu.

Ano, zní to možná divně, ale pojďme se podívat na ukázku:
const initialState = {count: 0};

class User extends React.Component<Props, typeof initialState> {
    readonly state = initialState;

    handleOnClick = () => {
        this.setState(({count}) => ({count: count++}));
    };
    
    render() {
        const {firstName, lastName} = this.props;
        const {count} = this.state;
        return (
            <div onClick={this.handleOnClick}>
                {firstName} {lastName} | Count: {count}
            </div>
        );
    }
}

Komponentu User jsme přepsali do třídy a přidali State. Součástí toho je výchozí state, který komponenta očekává. V našem případě začíname na count = 0. Proto jsme využili toho, že podle nadefinovaného výchozí stavu, jsme vytvořili i daný typ State. Stejným způsobem bychom mohli použít typeof i v případě defaultních hodnot pro props.

Readonly a readonly


Nejen v Reactu bychom se měli snažit o to, abychom psali více funkcionálně. Současně s tím je důležité se zaměřit na immutable stav. Tedy najít způsob, jak zabezpečit, aby daná hodnota nešla přepisovat přímo, ale vždy se vytvářela pouze nová kopie.  K tomuto účelu můžeme využít readonly, který nám zajišťuje, že daný atribut v objektu bude immutable (alespoň z pohledu TS).

Pojďme na ukázku:
interface Props {
    readonly firstName: string;
    readonly lastName: string;
    readonly type: UserType;
}

const initialState = {count: 0};

class User extends React.Component<Props, Readonly<typeof initialState>> {
    readonly state = initialState;

    handleOnClick = () => {
        this.setState(({count}) => ({count: count++}));
    };

    render() {
        const {firstName, lastName} = this.props;
        const {count} = this.state;
        return (
            <div onClick={this.handleOnClick}>
                {firstName} {lastName} | Count: {count}
            </div>
        );
    }
}

V ukázce jsou použity dvě varianty. První variantou je definování u props, kde každý atribut je označen pomocí klíčového slova readonly. Druhou variantou je State, kde je použit typ Readonly. Pokud bychom nyní chtěli napřímo mutovat atributy Props či State, tak TS nám bude hlásit chybu, že daný atribut je readonly.

Pick


Další skvělou vlastností je typ Pick. Tento typ slouží k tomu, abychom si z předem definovaného typu, vytvořili nový typ, který bude obsahovat pouze ty atributy, které dopředu určíme.

Pojďmě opět na ukázku:
type UserType = 'admin' | 'guest';

interface UserDataQuery {
    readonly firstName: string;
    readonly lastName: string;
    readonly type: UserType;
}

interface Query {
    data: UserDataQuery;
    roles: string[];
}

interface Props extends Pick<Query, 'data'> {}

const initialState = {count: 0};

class User extends React.Component<Props, Readonly<typeof initialState>> {
    readonly state = initialState;

    handleOnClick = () => {
        this.setState(({count}) => ({count: count++}));
    };

    render() {
        const {data} = this.props;
        const {count} = this.state;
        return (
            <div onClick={this.handleOnClick}>
                {data.firstName} {data.lastName} | Count: {count}
            </div>
        );
    }
}

const App = () => <User data={{firstName: 'Ales', lastName: 'Dostal', type: 'admin'}} />;

Často se setkáváme s tím, že máme například z GraphQL vygenerovaný typový model, ale ten, na úrovni Query obsahuje všechny možné atributy, které lze získat. Zde se výborně hodí onen typ Pick, který nám vytvoří typ, který vychází z typu Query. Obsahovat bude pouze ty atributy, které si sami určíme. V našem případě tedy atribut data.

Omit


Pokud pomocí typu Pick můžeme definovat atributy, které nový objekt má obsahovat, jeho protějškem je typ Omit. Ten naopak umí definovat, které atributy nový typ obsahovat nebude.

Pojďme na ukázku (v ukázce je Omit použi z knihovny recompose):
interface UserQuestProps {
    data: Omit<UserDataQuery, 'type'>;
}

const UserGuest: React.SFC<UserQuestProps> = (props) => {
    return <User data={{...props.data, type: 'guest'}} />;
};

const App = () => (
    <div>
        <User data={{firstName: 'Ales', lastName: 'Dostal', type: 'admin'}} />
        <UserGuest data={{firstName: 'Ales', lastName: 'Dostal'}} />
    </div>
);

V tomto případě jsme vytvořili novou komponentu UserGuest, která ovšem umožňuje, že i když vychází ze stejného datového typu UserDataQuery, tak odstraňuje atribut type, který je přímo nastaven na hodnotu guest.

V tomto případě je na zvážení, zda by ona komponenta UserGuest, neměla být napsána spíše jako HOC (Higher-Order Component). Ale o tom až jindy :)

Závěr


Vybral jsem pár zajímavých vlastností TS jazyka, se kterými se lze často setkat a zároveň i věci, které nejsou až tak známé (viz Pick či Omit). Příště se zkusíme podívat na některé další vlasnosti.

Na závěr ještě celá ukázka našeho příkladu:
type UserType = 'admin' | 'guest';

interface UserDataQuery {
    readonly firstName: string;
    readonly lastName: string;
    readonly type: UserType;
}

interface Query {
    data: UserDataQuery;
    roles: string[];
}

interface Props extends Pick<Query, 'data'> {}

const initialState = {count: 0};

class User extends React.Component<Props, Readonly<typeof initialState>> {
    readonly state = initialState;

    handleOnClick = () => {
        this.setState(({count}) => ({count: count++}));
    };

    render() {
        const {data} = this.props;
        const {count} = this.state;
        return (
            <div onClick={this.handleOnClick}>
                {data.firstName} {data.lastName} | Count: {count}
            </div>
        );
    }
}

interface UserQuestProps {
    data: Omit<UserDataQuery, 'type'>;
}

const UserGuest: React.SFC<UserQuestProps> = (props) => {
    return <User data={{...props.data, type: 'guest'}} />;
};

const App = () => (
    <div>
        <User data={{firstName: 'Ales', lastName: 'Dostal', type: 'admin'}} />
        <UserGuest data={{firstName: 'Ales', lastName: 'Dostal'}} />
    </div>
);

středa 23. května 2018

React aplikace od začátku do konce

V poslední době jsme byli nuceni napsat více React aplikací, které vždy vychází ze stejného základu. Díky tomu jsem si uvědomil, že i když můžeme jednoduše provést setup čistého projektu, přeci jen je několik částí, které je nutné doplnit vlastním kódem. To mě nakonec dovedlo k myšlence, že jsem vzal čistý list papíru (gitu) a napsal example projekt, který slouží jako základní dev stack.

A tak jsem vytvořil "Aldu"

DEMO: https://alda.app
Git repozitář: https://github.com/ApiTreeCZ/alda

Co je cílem tohoto projektu?


Je to hlavně demonstrace toho, jak lze jednoduše napsat React aplikaci, která má snad vše, co je třeba. Díky tomu je zde přesah i do dalších oblastí jako je třeba nasazení do Kubernetes v Cloudu, CI/CD, apod.

Proč vlastní řešení?


Hlavním důvodem je, že díky rychlé evoluci JavaScript technologií se často dostáváme do stavu, kdy aktualizace jedné knihovny zapříčiní problémy v celém systému. Proto je snaha, aby tento projekt používal co nejaktuálnější knihovny a neustále dokola opravoval problémy, které vznikají s novými verzemi. Ano, svět JavaScriptu má i odvrácenou temnou stranu a tou je "jepičí život" některých knihoven a verzí.

Dalším důvodem je to, co již bylo zmíněno na začátku. Tedy využití Aldy pro start nových projektů.

A nakonec to nejdůležitější a tím je, že když chci propojit několik technologií, tak je velice malá pravděpodobnost, že najdu kompletní řešení. Vždy musím někde napsat nějakou část kódu, která nás nutí k tomu, abychom se stále probírali různými možnostmi, jak to vlastně udělat.

Co ten systém umí?


Tak hlavně je to React a to stačí :) .... Teď važně.

Jedná se React (už zase :)) aplikaci napsanou pomocí TypeScriptu. Celý systém je napsán přes Next.js, tudíž automaticky se jedná o isomorfní aplikaci, která podporuje server side rendering. Díky tomu jí lze nasadit na veřený web a není důvod se bát kvůli SEO a indexování od vyhledávačů.

Abychom trochu dodrželi štábní kulturu, tak v projektu je implementován TSLint a Prettier. Tedy kontrola na zápis kódu a zároveň automatické formátování podle předepsaných pravidel. Statická analýza kódu je v JavaScript světě nutností.

Celý systém je postaven na knihovně material-ui, která před pár dny vyšla oficiálně ve verzi 1.0. Díky tomu jsou CSS psány pomocí JavaScriptu a nakonec generovány jako css třídy.

Dále obsahuje Redux, do kterého si ukládá globálně důležité stavy. Díky tomu je zde redux-form, což je knihovna pro formuláře.

Pro lokalizaci je zde použitá knihovna react-intl, díky které je možné jednoduše používat překlady a to nejen textové, ale i číselné a datumové. Součástí toho je zde napsán vlastní systém generování výchozího jazyka a mergování do ostatních. V praxi to znamená, že když mám třeba výchozí angličtinu a přidám další jazyk, tak texty, které jsem v novém jazyce ještě neimplementoval, budou automaticky v angličtině.

Pro komunikaci s backendem je zde GraphQL a to v implementaci přes Apollo (sorry, ale Relay není ta cesta). Současně s tím je zde i malý backend server, který je vlastním GraphQL serverem. Vedle toho jsou zde navíc použity knihovny, které umožňují samotné GraphQL schéma generovat do TypeScriptu a tím pádem máte zadarmo celý API model a to jak na straně frontendu tak i backendu.

Další částí, která zatím není implementována, ale bude co nejdříve, je přihlašování pomocí JWT tokenu. Tedy autentizace přes login a heslo a autoriace přes JWT token.

Poslední důležitou součástí je příprava pro psaní testů pomocí knihovny Jest. Vedle toho je navíc integrace se službou Coveralls, která na základě výsledků testů provádí analýzu a říká nám, na kolik procent je náš kód pokrytý testy.

Nasazení do Cloudu


Pokud jsem na začátku zmínil, že jsem vytvořil základní stack pro vývoj React aplikací, tak je to jen 50% toho, co jsem udělal. Druhou částí je samotný způsob, jak aplikace funguje z pohledu DevOps.

Pokud to zjednoduším, tak Alda funguje tak, že pokud udělám přes GitHub nový release, tak se automaticky vytvoří Docker image, který se nasadí v Google Cloudu do Kubernetes clusteru přes Helm. Pokud nasadím aplikaci na novou doménu, tak automaticky vytvoří SSL certifikát přes Lets Encrypt. Je prostě cool, když nakonec jedním příkazem nasadíte celý ekosystém, který je škálovatelný. Jediné omezení je pak Vaše peněženka, ze které si musíte zaplatit tolik serverů, kolik uznáte za vhodné.

Celý proces nasazení je popsán v definici pro CircleCI. Ano, Alda používá CircleCI, což je jeden z nejlepších nástrojů pro CI/CD současnosti.

Plány do budoucna?


Na to je jednoduchá odpověď a tím jsou GitHub issues: https://github.com/ApiTreeCZ/alda/issues.

Jedna z věcí, kterou je třeba provést je samotný refactoring. Více implementovat vzory jako třeba: "Higher-Order Components" apod.

Pokud byste něco nového chtěli přidat, neváhejte poslat požadavek :)

Závěr


Hlavním důvodem, proč jsem chtěl sepsat tento článek není ani tak to, že bych chtěl naše řešení nějak propagovat, ale spíše pomoci ostatním, který řeší podobné problémy jako my. Ať už se jedná třeba o spojení material-ui s Next.js či o nasazení do Kubernetes.

Někdy příště popíši blíže celý projekt z pohledu samotného vývoje.

pondělí 9. dubna 2018

DevOps a Release management

Release management je proces, který je dnes přímo spojen s věcmi jako je Continuous Integration, Continuous Delivery (ve zkratce CI/CD), Git, Docker, apod. Díky tomu se z Release managementu stává obor, který vyžaduje vcelku hluboké znalosti v IT oboru. V dnešním článku se pokusím rozebrat, jakým způsobem k Release managementu přistupujeme my a jak do tohoto procesu zakomponovat ostatní moderní technologie jako je Docker, apod.

Verzování


Základním předpokladem je určení, jakým způsobem verzovat. První variantou je, že si sami vytvoříme verzování podle svého vlastního uvážení. To ovšem nedělejte. Vymýšlení "kola" je to nejhorší, co můžete udělat. Chápu, že každý z nás chce být průkopníkem ve své oblasti, ale je velice malá pravděpodobnost, že se Vám to podaří. Nicméně, pokud máte ambice, že změníte IT svět a nastavíte novou specifikaci pro verzování, směle do toho.

Druhou a mnohem lepší variantou je, že zvolíte již existující návrh. Tím je specifikace, která se označuje jako Sémantické verzování, zkráceně SemVer. Tuto specifikaci vytvořil Tom Preston-Werner, což je spoluzakladatel GitHubu. Samotná specifikace je vcelku jednoduchá a její osvojení je otázka několika hodin. Výhodou tohoto řešení je zejména fakt, že pokud dodržíte tuto specifikaci, je mnohem větší pravděpodobnost, že konzumenti Vašeho API, knihovny, či celého systému porozumí Vašemu verzování. Nebudete muset nikomu vysvětlovat, že když jste zvýšili MAJOR verzi, že tím automaticky říkáte, že Váš systém je zpětně nekompatibilní, apod.

Vedle toho je SemVer vhodné i pro vývoj, tedy v době, kdy sice v produkci ještě nejste, ale potřebujete si v projektu udělat trochu pořádek a jednoduše zajistit, aby se do vyšších prostředí nedostalo něco, co tam nepatří.

Následující popis počítá se znalostí SemVer.

Verzování a Git


Samotný Git je sice označován jako distribuovaný systém správy verzí, ale to ještě neznamená, že použitím Gitu mám vyřešen Release management. Naopak. Git slouží pouze jako prostředek k tomu, jak Release management uskutečnit.

Pokud dáte do spojení Release management a Git, s největší pravděpodobností skončíte u něčeho, co se jmenuje Gitflow.

Gitflow

Jedná se o specifikaci, která určuje, jakým způsobem řídit Váš projekt od prvního řádku kódu až po produkční verzi. Vedle toho také definuje, jak řešit věci jako je release nové verze, opravy na stávajících verzích, apod.

Gitflow vychází z předpokladu, že díky Gitu máte možnost jednoduše vyrábět větve a ty mezi sebou zase spojovat a štítkovat (tagovat). Díky tomu si můžete ušetřit několik bezesných nocí, kdy budete přemýšlet nad tím, jak se zachovat, když například máte v produkci verzi 1.0.3 a vy už pracujete na verzi 2.0.0, ale zároveň potřebujete opravit něco ve verzi 1.0.3 a danou opravu udělat jak pro produkci, tak i pro stávající vývoj.

Gitflow je robusní řešení, které pokrývá všechny známé problémy při dodávce. Vedle toho je to návrh, který předpokládá, že v produkci máte několik verzí. Gitflow je vcelku rošířená specifikace, se kterou se lze často setkat. Otázkou jen je, jestli skutečně Gitflow potřebujeme.

Důvodů, proč neskočit po tomto řešení je hned několik. Prvním důvodem je to, že toto řešení je příliš komplexní a často se dostáváte do situace, kdy kvůli jedné malé změně musíte "mergovat první ligu". Druhou nevýhodou je to, že pokud vydáváte nové verze agilněji, tedy v rychlých iteracích, tak je Gitflow něco, co skutečně nechcete. Další nevýhodou je to, že je velká pravděpodobnost, že se v tom někteří vývojáři budou ztrácet a samotný Release management tak bude výsadou jen těch, kteří perfektně znají Gitflow. Tady platí pravidlo, že méně je někdy více.

Když jsem řešil samotný Release management, tak po prostudování několika specifikací a po ohlédnutí se zpět, na projekty, na kterých jsem pracoval, tak se mi v hlavě točila pořád a jedna a ta samá otázka. Skutečně Gitflow potřebuji? Co mi to nakonec přinese? Je to pro projekt, na kterém pracuji, vhodná specifikace? Nakonec jsem dospěl k tomu, že nikoli.

Github release

Další variantou, jak vyrábět release je pomocí Githubu. Pokud své projekty máte v Githubu, ať už jako privátní repozitáře či veřejné, máte možnost v určitém momentu udělat release. Onen release nemusí být jen produkční, ale také pre-release, což znamená, že se jedná o určitý milník ve vývoji, kterým si označíte Váš poslední commit. Tento pre-release může být vhodný třeba pro nasazení na vyšší prostředí, než je Vaše vývojové. Třeba pro demo, testy apod.

Samotný Github release nedělá nic jiného, než to, že přidá tag na daný commit. Buď podle větve a nebo na jasně definovaný commit. Je vcelku na Vás, kde daný tag umístíte, jde spíše o to, že ho umístíte.

Další věcí je i to, že při vytvoření releasu Vám Github nabízí možnost napsat Release notes. Tedy k dané verzi sepsat poznámku, ve které jasně specifikujete, co nová verze obsahuje, jaké bugy opravuje, apod. Přiznám se, že Release notes je věc, která je nesmírně důležitá a zároveň nejvíce ignorovaná mezi vývojáři. Je sice hezké, že jste vytvořili novou verzi, ale bez popisu dané verze je to spíše jen tvorba verze pro Vás, nikoli pro ostatní. V případě, že píšete knihovnu, kterou má konzumovat někdo další, tak absence Release notes je kontraproduktivní i pro Vás. Vždy, když použiji nějakou knihovnu, tak se koukám, zda vývojáři píší ony poznámky. Pokud ne, knihovnu ignoruji a jdu jinam. Veřte, že nejsem jediný.

Když jsem si dal na misku vah plusy a mínusy mezi Gitflow vs Github releases, tak jsem nakonec dospěl k závěru, že raději zvolím Github. Jednak pro jeho jednoduchost, ale také pro to, že je plně postačující. Jsem presvědčen, že pro drtivou většinu projektů to tak je. Když jsem přemýšlel, kde by mi Github releases nestačil, nebyl jsem schopný žádný takový příklad najít. Pokud Vás nějaký napadne, budu rád, když se o tento případ podělíte. Samozřejmě v případě absence Githubu můžeme říci, že release je řízen tagováním, což je ve výsledku to samé, akorát často přijdete o ony hezky zobrazené Release notes.

Abyste měli představu, jak takové releases v Githubu vypadají, podívejte se třeba na knihovnu React.

Verzování a Docker


Pokud dnes mluvíme o dodávce softwaru, který je server side charakteru, tak bychom druhým dechem měli říct, že ho dodáváme pomocí Docker image. V případě, že Docker nepoužíváte, ale chtěli byste, věřte, že si tím neskutečně ušetříte problémy při integracích a dodávce směrem k provozu.

Díky tomu, že Docker image je tagována, tak se tím přímo nabízí, aby byla tagována tak, jak jsou tagovány jednotlivé verze. Více se o verzování Docker image zmíním dále, v ukázkovém projektu.

Verzování a NPM


V případě, že píšete aplikace v javascriptu, je vcelku jedno, zda serverové či klientské, tak jistě používáte hromadu knihoven, na kterých jste závislí. Vedle toho se ovšem často dostanete do fáze, kdy byste si i Vy sami chtěli vyrobit vlastní knihovnu, která Vám umožní nasdílet si části kódu mezi jednotlivými systémy.

K tomuto účelu slouží právě NPM repozitář. A světě div se, ale i NPM podporuje verzování. Dokonce používá specifikaci SemVer. Tudíž je vcelku jasné, že i zde použijete stejný přístup. Více opět v ukázce.

Verzování a CircleCI


Pokud mluvíme o Release managementu a dodávce softwaru, tak bychom si měli najít nástroj, který nám pomůže s tím, abychom automatizovali to, co automatizovat lze. Tedy o nástroji, který se označuje jako CI/CD.

Nejznámějším a asi možná i nejpoužívanejším je Jenkins. Hromada lidí má s Jenkinsem zkušenosti a jistě Vám řeknou, že je skvělý. Po pravdě, osobně Jenkins nesnáším. Nesnáším je možná silné slovo, ale nespatřuji v něm příliš velkou výhodu oproti ostatním. Asi tím nejzásadnějším je fakt, že Jenkins lze použít pouze jako On-premises, tedy musíte si ho "někam" nainstalovat.

Moje osobní zkušenost s Jenkinsem je taková, že jsem zažil instance, které byly příšerně pomalé a vytvořit v něm "job", chtělo notnou dávku trpělivosti, která mi scházela. I když s Jenkinsem pracovat umím, vůbec mi nebude vadit, když ho již nepotkám.

V době, když jsem hledal smysluplnou alternativu, která bude navíc fungovat jako služba, tudíž nepotřebujete člověka, co se Vám musí starat o Váš vyšperkovaný Jenkins, nalezl jsem několik variant. Osobně jsem si nejvíce zamiloval CircleCI a to z několika důvodů.

První věcí je tedy to, že funguje jako služba. Další výhodou je to, že má vcelku jednoduché použití. Tedy nemusíte vystudovat 5 vysokých škol, abyste byli schopni napsat jednoduché joby. Dále je to fakt, že každý job, který spouštíte je spuštěn ve vlastním Docker kontejneru a tím se od sebe jednotlivé joby izolujete a můžete je spouštět paralelně. Dané joby pak nadefinujete do workflow a určíte závislosti mezi nimi. Typickým příkladem je, že pokud nedoběhne build projektu, nespustí se deploy, apod.

CircleCI neumožňuje vyrábet Joby bez zdroje. Tedy každa akce je vázána na repozitář v Gitu. Tohle pro někoho může být blokující, ale já to vnímám jako výhodu. Jakým lepším způsobem si verzovat joby, než přímo Gitem? A věřte, jde to i bez toho, jen je třeba občas se nad danou věcí jinak zamyslet. Tím, že CircleCI podporuje i scheduler, tedy opakované spouštění jobů v určitý čas, lze říci, že je to plnohodnotná alternativa.

Poslední věcí, kterou bych chtěl zmínit je to, že CircleCI je spojen s BitBucketem nebo Githubem. Nepotřebujete tedy speciálně pro CD/CI definovat oprávnění a něco složitě nastavovat, ale ono oprávnění je přebíráno právě z těchto systémů pro Git. Pokud jste ve Vaší privátní organizaci na Githubu administrátorem, budete administrátorem i zde, apod.

CircleCI je pro mě osvobozující v tom, že dělá jen to, co dělat má. Tam jeho role začíná i končí.

Ukázkový projekt


Nyní se přesuňme k druhé části, která ma za cíl ukázat, jakým způsobem náš proces úspěšně nastartovat a zároveň provozovat i v produkci.

Nejprve si nadefinujme projekt, který se skládá ze tří částí:

1. Frontend v Next.js
2. Backend v Node.js
3. Knihovna X

Frontend pro svojí činnost potřebuje bežící Node.js a zároveň používá knihovnu z NPM, tedy naší Knihovnu X. Backend také běží nad Node.js a připojuje se k databázi. Poskytuje tedy vrstvu mezi databází a frontendem. Zároveň i backend používá naší Knihovnu X z NPM jako závislost.

Náš projekt bude dodáván formou Docker image a poběží v Azure Cloudu v Kubernetes.

První setup


Prvním krokem je inicizalizace našich systému do Gitu. Budeme mít tři Git repozitáře (Frontend, Backend, KnihovnaX). Inicializaci můžeme udělat v master větvi, ale hned bychom měli vyrobit větev s názvem dev (potažmo devel či develop).

Druhým krokem je definování verze v package.json. Pokud začínáme, označme verzi jako: 0.1.0-alpha.1. Tím, že nám SemVer říká, že do produkce nemůže jít nic, co začíná 0, tak alespoň víme, že v produkci ještě nejsme. Pokud již systém existuje a to i v produkci, tak záleží jak moc jsme verzování ignorovali. Pokud úplně, nastavil bych verzi jako: 2.0.0-alpha.1. Rovnou říkáme, děláme verzi 2 a verze 1 bylo vše předchozí :)

Vývoj


Pokud na daném projektu či repozitáři pracujeme sami, klidně můžeme vše commitovat do naší dev větve. Jsme tam sami, takže proč ne. V případě, že nás pracuje na projektu více, je lepší si vytvořit vlastní větev. Například tak, že si vytvořím novou větev z větve dev a do názvu dám: feature/xxx. Pod názvem xxx by se mělo vyskytovat to, co skutečně děláme. Ve chvíli, kdy svou činnost máme hotovou, zamergujeme naší větev feature/xxx do větve dev. A tak stále dokola. Každopádně nezapomínejte po sobě dané větve mazat.

Vedle toho můžeme rovnou použít CircleCI a říci, že pokud někdo uloží něco do větve dev, spustí se následující scénář (frontend, backend):

1. Build projektu (npm install, tsc, tslint, apod)
2. Test projektu (unit testy, apod)
3. Tvorba Docker image (s tagy: "commit hash" a "dev")
4. Deploy (deploy projektu do Kubernetes)

Krok 1 a 2 je vcelku jasný. Krok 3 říká, že vytvořím Docker image, kde commit hash je unitátní a tudíž bude možné kdykoli nasadit verzi Docker image podle commitu. Tag dev v Docker repozitory se bude neustále přepisovat. Ale zase nám umožní, vytvořit prostředí, které bude z posledních commitů z dev větví.

Krok 4 je deploy, což znamená, že pokud je již systém běžící, tak stačí pouze aktualizovat Docker image tag v prostředí dev. Nejlépe podle commit hash.

Co se týče knihovny, tak workflow by bylo jednodušší:

1. Build projektu
2. Test projektu

První pre-release


Nyní se přesuňme k tomu, že v rámci Githubu vytvoříme svůj první release. V tomhle případě začněme rovnou naší knihovnou, protože tu budete muset releasovat jistě jako první.

Poté, co v Githubu provedete release, tak se do Gitu zapíše tag. Při releasování v Githubu, zapíšete verzi takto: v0.1.0-alpha.1. CircleCI umí zareagovat i pouze na push tag a spustí následující workflow:

1. Build projektu
2. Test projektu
3. Publish do NPM (tag: alpha, verze: 0.1.0-alpha a 0.1.0-alpha.1)

V NPM repozitáři budete verzi 0.1.0-alpha přepisovat každým vydáním nove alpha verze.

Nyní si v naší knihovně (v dev větvi) otevřeme soubor package.json a verzi přepíšeme na 0.1.0-alpha.2. Následuje další vývoj, až do doby, kdy se rozhodneme, že by stálo za to, opět udělat nový pre-release.

Co se týče frontendu a backendu, tak budeme postupovat úplně stejně. Rozdílné bude pouze naše workflow:

1. Build projektu
2. Test projektu
3. Tvorba Docker image (s tagy: "0.1.0-alpha" a "0.1.0-alpha.1")

A opět v dev větvi zvýšíme verzi na: 0.1.0-alpha.2.

Tímto způsobem jsme vytvořili první pre-release.

Je dobré ještě zmínit, že samotné verzování je hodně na Vás. Nicméně byste měli z alpha verze přecházet do beta verze a poté do Release candidate (rc). Tímto způsobem byste měli postupně dojít až do produkce. Použití těchto identifikátorů je následující:

1. Alpha říká, že funkcionalita je nekompletní a rozpracovaná
2. Beta říká, že funkcionalita je již téměř kompletní, ale může obsahovat chyby
3. Release Candidate říká, že funkcionalita je vyvinuta a opravují se jen chyby

Další variantou je, že s jednotným identifikátorem dojdete až před produkci. Určitě ale nemodifikujte samotnou verzi. Je nežádoucí, aby v rámci vývoje došlo k tomu, že z verze 0.1.0 udělám verzi 0.2.0 apod. To patří do produkce.

Pokud jste pečlivě prostudovali SemVer, tak jste jistě narazili i na to to, že v rámci pre-release identifikátoru můžete být více konkrétní. Klasickým příkladem je to, že alpha.x je málo vypovídající. Nic nebrání tomu, aby se verze označila třeba takto: 0.1.0.-alpha.1+api.3. Je jen na Vás, co vše chcete v pre-release identifikátoru evidovat. Samozřejmě bych to s výčtem informací nepřeháněl :)

Pre-release je stav, kdy vývoj říká, že splnil nějaký milník. Něco, kdy stojí za to, aby provedl pre-release a tím nabídnul své dílo vyššímu prostředí (demo, testy, apod). Vedle toho není cílem, aby všechny projekty měly stejné číslo v identifikátoru alpha. Vývoj jen řekne, že pro sestavení prostředí z posledního milníku je třeba:

Frontend: 0.1.0-alpha.7
Backend: 0.1.0-alpha.12
Knihovna: 0.1.0-alpha.4

Popřípadě můžete říct, že použití verze 0.1.0-alpha, vždy použije poslední existující release v alpha fázi.

Určitě doporučuji, aby pre-release vznikal tak často, jak to jen lze. V rámci konce sprintu (jednou za 14) je maximum. Klidně může vznikat častěji a to je žádoucí. Přeci jen, chceme říkat, že jsme "agilní" :)

První produkční release


Pokud již nastal čas, management už je naštvaný, že jsme po termínu, přejdeme k oficiálnímu releasu. Ten uděláme tak, že v našich package.json souborech nastavíme verzi na: 1.0.0 a tento commit zamergujeme do master větve. Poté přes Github uděláme release.

V NPM nám vznikne knihovna s číslem verze 1.0.0. Pro Docker image zvolíme tagy: 1, 1.0, 1.0.0 a latest. Důvod, proč bychom měli opět vyrábet více tagů je ten, že poté si můžeme zvolit, jakým způsobem budete sestavovat produkci či jiné prostředí. Pokud zvolíme verzi 1, tak říkáme, aktualizuj se vždy, když někdo vytvoří produkční release 1.x.x. Pokud 1.0, tak totéž platí pro 1.0.x, apod. Latest je tag, kterým se definuje poslední existující stabilní verze a navíc je pro Docker výchozí.

V rámci Docker tagů můžete použít i kódové označení. Jedním z příkladů je třeba Docker image pro Node.js.

Nyní se vrátíme k naší dev větvi a verzi nastavíme na 1.1.0-alpha.1.

Opravy chyb na produkci


Možná jste si všimli, že jsme v dev větvi použili verzi 1.1.0-alpha.1 a ne 1.0.1-alpha.1. Důvod je ten, že pokud se na produkci vyskytne závažná chyba, která musí být opravena dříve, než bude nový release, tak její oprava bude mít verzi: 1.0.1.

Oprava chyby se provede tak, že se vytvoří nová větev z tagu 1.0.0. Název branche by měl být hotfix/xxx, kde pod xxx se může skrývat identifikace chyby. Poté, co je chyba opravena a otestována, je zamergována zpět do master větve a vydána jako verze: 1.0.1. Současně s tím bychom daný hotfix měli zamergovat do naší dev větve a následně branch hotfix/xxx smazat.

Následný vývoj


Jak už jsme si řekli, tak následný vývoj bude mít verzi 1.1.0-alpha.1. Nicméně může se stát, že nový release bude znamenat nekompatibilitu s předchozí verzí. V tom případě bychom verzi nastavili jako: 2.0.0-alpha.1.

V této chvíli se můžete vrátit ke kapitole Vývoj, protože přesně na tom místě se nyní nacházíme...

Závěr


Jsem si vědom toho, že existuje tisíce patternů, jak řídit samotnou dodávku softwaru. Každopádně cílem bylo Vám ukázat jednu z cest, kterou když se vydáte, tak jistě neselžete.

Stejně tak lze mnohem více věcí automatizovat, viz třeba ruční přepisování package.json souborů. Ale vždy je zatím skryto určité nebezpečí. Tím nebezpečím je fakt, že automatizace je dobrá cesta, ale do určitých limitů. Mohlo by se Vám totiž jednoduše stát, že touha po dokonalé automatizaci končí šílenými bash/python/perl skripty, které jsou často jen náhradou ručního releasu. Za mě, ona automatizace končí přesně ve chvíli, kdy se dostanu do míst, kde musím řešit příliš mnoho výjimek a pravidel.

A co vy? Jak řešíte Release management?


neděle 1. dubna 2018

DevOps s Kubernetes a Helm Charts


V poslední době jsem byl nucen se více zaměřit na integraci mezi vývojem a provozem. Poté, co jsem si prošlapal několik slepých uliček, jsem nakonec skončil u technologie, která se pomalu stává hlavním tématem ve spojení s Cloudem. Kubernetes. Platforma, kterou si zamilujete.

Než se dostaneme ke Kubernetes a Helm Charts, pojďme se podívat na svět, kde tyto technologie neexistují.

Cesta mezi zdrojáky v gitu a provozem je často dlouhá, krkolomná a křehká. Zažil jsem projekty, kde integrace znamenala, že se ručně nakopíroval build na ostrý provoz přes FTP. Projekty, kde díky absenci CI/CD se integrace vlastně nekonala, ale byla tvořena pouze z jednoho lokálního PC. A také projekty, kde integrace byla tak složitá, že bylo třeba zaměstnat několik lidí v roli DevOps, kteří tvořili křehké bash/python/perl skripty, které chápal pouze autor.

V takovém prostředí je vždy nutné mít několik programátorů/administrátorů, kteří jsou fulltime výtíženi jen tím, aby udrželi aktuální stav. Ve chvíli, kdy dochází produkčnímu nasazení, jedná se spíše o ruskou ruletu. Před takovou akcí dochází k modlitbám a lidem v hlavách běží několik otázek: "Bude to fungovat? Jak se jednoduše vrátíme zpět? Cože? Horizontálně škálovat?! Máme správné verze?" Tohle peklo se často ještě násobí počtem systémů, které musíme nasadit.

Vedle samotného nasazení na produkci se DevOps často stará i o to, aby vývoj, potažmo ostatní účastníci projektu, měli svá prostředí. Pokud nejsme naprostí ignoranti, je jasné, že pouze s jedním prostředím typu DEV si nemůžeme vystačit. Poté přichází na řadu prostředí pro testery, prostředí pro demo, prostředí na preprod simulaci, apod. Nedej bože, aby vývoj chtěl prostředí podle git větví. Není neobvyklé, že takových prostředí můžeme mít klidně i několik desítek. Často se nakonec dostáváme do stavu, kdy začneme ohýbat release management, protože jinak bychom do produkce nikdy nic nedostali. Chaos, který se nedá narovnat jinak, než zásadní změnou použitých technologií...

Pojďme se nyní pokusit z takového stavu vymanit a v podstatě se dostat do stavu, kdy samotná role DevOps se stane vlastně zbytečnou, popřípadě umožní nám zredukovat potřebné množství lidí, kteří by nám někde po serverech psali bash skripty. Aby následující popis nebyl příliš abstraktní, pojďme si navrhnout projekt, kterého se to bude týkat.

Návrh projektu


Náš projekt se skládá ze šesti systémů (každý systém je uložen ve vlastním git repozitáři):
  1. Frontend - hlavní UI našeho projektu
  2. Backend - hlavní backend pro UI a současně poskytuje veřejné API
  3. Admin - admin rozhraní
  4. Backend-admin - backend pro administraci
  5. Backend-int - integrační backend mezi naším projektem a ERP systémem pod námi
  6. Tool-ui - pomocný nástroj, který sleduje náš systém, slouží pouze pro vývoj

Běh projektu má následující předpoklady:
  • Databáze
  • Frontend, Backend a Admin musí být přístupný na doméně přes SSL, ostatní systémy nesmí být dostupné na veřejné doméně či IP adrese
  • Certifikáty pro komunikaci mezi Backend-int a ERP systémem
  • Projekt běží v Cloudu (Azure či Google Cloud)
  • CI/CD server - například CircleCI

Součástí vývoje je nutné mít i několik prostředí. Každé prostředí obsahuje vlastní databázi a je plně autonomní. Tvorba prostředí vlastně znamená tvorbu databáze a serverů, na kterých běží náš projekt. Pro naše účely si představme, že máme tyto prostředí:
  • dev - prostředí pro vývoj
  • test[0-9] - až 10 testovacích prostředí
  • uat - prostředí pro uživatelské akceptační testy
  • preprod - protředí simulující produkci, tedy na produkčních datech
  • prod - produkční prostředí

Krok první: Docker


O Dockeru jsem psal v minulém článku Vývoj aplikací přes Docker. V dnešní době si vývoj bez Dockeru neumím ani moc představit. Těch výhod, které Vám Docker nabízí je totiž tolik, že i přes prvotní krkolomné rozeběhnutí se nakonec budete ptát sami sebe: "Proč jsem sakra s Dockerem nezačal už dříve".

Součástí samotné "dockerizace" Vašich systémů je nutné myslet i na správné verzování. K verzování Vám slouží samotné Docker tagy. Zde Vás odkážu na článek, popisující samotné verzování.
Vedle verzování je možné Docker image ukládát i do privátních repozitářů. Ať už v rámci Cloudu, kde často najdete něco jako Container registry, tak třeba i v Docker Hubu.
Každopádně samotný Docker image NESMÍ obsahovat žádné citlivé informace. Pokud do běžícího Docker kontejneru potřebujeme dostat informace o připojení k databázi, nechte toto nastavení na Kubernetes.

Nyní Vám ukážu příklad, jak v CircleCI vytvořit Docker image a ten uložit do privátního Docker registry v Azure:
version: 2
jobs:
  create_docker_image:
    working_directory: ~/docker-image
    machine: true
    steps:
      - checkout
      - attach_workspace:
          at: ~/docker-image
      - run:
          name: Docker login
          command: docker login ${AZURE_DOCKER_URL_SERVER} -u ${AZURE_DOCKER_USERNAME} -p ${AZURE_DOCKER_PASSWORD}
      - run:
          name: Set docker image to workspace
          command: mkdir -p workspace && echo "${AZURE_DOCKER_URL_SERVER}/xxx/${CIRCLE_PROJECT_REPONAME}" > workspace/docker-image
      - run:
          name: Show docker image
          command: cat workspace/docker-image
      - run:
          name: Docker create image
          command: docker build --build-arg GIT_COMMIT=${CIRCLE_SHA1} --build-arg GIT_BRANCH=${CIRCLE_BRANCH} --build-arg BUILD_NUM=${CIRCLE_BUILD_NUM} --build-arg BUILD_AUTHOR=${CIRCLE_USERNAME} -t $(cat workspace/docker-image):latest .
      - run:
          name: Docker create tag CIRCLE_BRANCH
          command: docker tag $(cat workspace/docker-image) $(cat workspace/docker-image):${CIRCLE_BRANCH}
      - run:
          name: Docker create tag CIRCLE_SHA1
          command: docker tag $(cat workspace/docker-image) $(cat workspace/docker-image):${CIRCLE_SHA1}
      - run:
          name: Docker push
          command: docker push $(cat workspace/docker-image)
      - persist_to_workspace:
          root: .
          paths:
            - workspace
            - .circleci

workflows:
  version: 2
  build_and_deploy:
    jobs:
      - create_docker_image:
          context: xxx-context
          filters:
            branches:
              only:
                - dev

Job s názvem create_docker_image provede několik věcí:

  1. Přihlásí se pomocí Docker login do privátního Docker registry
  2. Vytvoří Docker image s tagem latest
  3. Do Docker image uloží informace jako: commit hash, git branch, číslo buildu, autora buildu
  4. Vytvoří další tag podle git větve
  5. Vytvoří další tag s git hash commitem
  6. Pushne dané tagy do privátní Docker registry
V ukázce je navíc použit workspace, což je vlastnost CircleCI, která umožňuje předat hodnoty dalším jobům v rámci workflow.

Výsledkem je, že v Docker repozitory budeme mít Docker image s tagy: latest, dev a commit hash. Důvod, proč verzujeme Docker image více tagy je jednoduchý. Představte si situaci, že používáte Docker image s tagem dev. Co když je ovšem onen image rozbitý a my rychle potřebujeme nasadit jeho předchozí verzi? Není nic jednoduššího, než si dohledat předchozí commit a nasadit image podle commit hash.

V případě releasu jsou Docker image tvořeny z master větve a verzovány podle git tagu. Pokud řeknu, že vytvářím novou verzi například: 2.3.7, tak se vytvoří či přepíší následující tagy: latest, 2, 2.3 a 2.3.7. Ale více se už dozvíte z výše odkazovaného článku o verzování Docker image.
Další variantou verzování vývoje je přes pre-release podle SemVer. Nicméně, zůstaňme u této zjednodušené varianty.

V této chvíli bychom mohli samotný Docker image nasadit a říci, že máme hotovo. Po pravdě, přímé nasazování samotných Docker images nám sice částečně pomůže, ale tím zdaleka nekončíme.

Stačí si jen zodpovědět otázku: "Jak vytvořím celé prostředí, když nasazuji pouze jeden systém?" Onen systém potřebuje databázi, potřebuje i okolní systémy a tím pádem bychom se stále museli zabývat tvorbou prostředí ala bash skripty v DevOps.

Krok druhý: Kubernetes


Když jsem přemýšlel, že napíši článek o Kubernetes, uvědomil jsem si, že vlastně nevím, kde přesně začít. Těch věcí je tolik, že na konci si řeknete: "Uff...". Na druhou stranu si ale zase uvědomíte, že to vlastně není nic složitého a vlastně jde jen o další abstrakci. Pojďme si Kubernetes vysvětlit trochu zjednodušeně.

Jednou větou se dá říci, že Kubernetes slouží na orchestraci běžících Docker kontejnerů. Zkusme si v několika bodech ukázat, kde všude nám může pomoci.

  • Tvorba bezvýpadkového systému
  • Škálování (horizontální i vertikální) za běhu
  • Load balancing
  • Správa celého prostředí
  • Možnost provést rollback, vrátit se k předchozím verzím
  • Uzavřít systémy uvnitř VNETu a vystavit ven pouze některé systémy
  • Globální nastavení proměných jako jsou hesla či hodnoty ovlivňující chod systémů
  • Jednoduše přes interní DNS provázat systémy mezi sebou
  • Před veřejné endpointy nasadit například nginx s automatickým Lets Encrypt SSL certifikáty
  • Automatické horizontální škálování, například v případě zátěže se po 5 minutách začnou automaticky vytvářet nové servery a případě snížení záteže se po dalších 5 minutách začnou mazat až do předem definovaného minimálního množství
  • Změnu provádět vždy deklarativně, tedy nebát se jako v případě imperativního zásahu, že shodím celý systém
  • Oddělit od sebe jednotlivá prostředí
  • Ideální platforma na tvorbu multitenantních systémů
  • Nebýt závislý na Cloud platformě

Kubernetes za Vás nevyřeší to, zda jste kvalitně otestovali svůj systém. Vyřeší ovšem za Vás to, že Vás odstíní od věcí, které byste si museli sami pracně udržovat pomocí různých podpůrných systémů.

Za největší výhodu považuji deklarativní ovládání celé platformy. Pomocí vlastních šablon říkáte, co se má v budoucnu stát. Příkladem je Deployment.

Deployment


Pomocí objektu Deployment definujete, jaký systém a v jaké konfiguraci se má nasadit. Součástí šablony pro Deployment jsou i další věci jako je například informace o tom, jaký Docker image se má spustit, s jakými parametry a třeba kolik se má vytvořit serverů.
Poté, co onen Deployment pošlete do Kubernetes, tak on si ho zařadí do své fronty požadavků a v budoucnu začně zpracovávat.

Pojďme se podívat na příklad Deployment objektu:
apiVersion: apps/v1
kind: Deployment
metadata:
  name: frontend-deployment
spec:
  replicas: 2
  template:
    metadata:
      labels:
        app: frontend
    spec:
      containers:
      - name: frontend
        image: url/frontend-image:1.0.3-dev
        env:
        - name: PORT
          value: "8080"
        - name: NODE_ENV
          value: "production"
        ports:
        - containerPort: 8080
      imagePullSecrets:
      - name: image-secret

Tento plán nám říká, že do Kubernetes nasadíme systém s názvem frontend, který je z Docker image frontend-image:1.0.3-dev. Navíc onen Docker image je z privátní repozitory, k němuž najde přístup v Secret objektu s názvem image-secret. Secret je další objekt, který se definuje podobně jako objekt Deployment

Daný Docker kontejner bude mít dvě proměné a to PORT a NODE_ENV. Systém se nasadí ve třech Podech. Pojem Pod v Kubernetes znamená běžící jednotku. Zjednodušeně řečeno, můžeme na ní koukat jako na běžící Docker kontejner.

Abychom tento Deployment nasadili, stačí spustit následující příkaz:
kubectl apply -f deployment.yaml

V případě, že již takový Deployment existuje a tudíž i existují bežící Pody, tak Kubernetes neudělá to, že by předchozí zastavil a nasadil nové, ale nejprve si vytvoří nový Pod a v ramci něho se pokusí onen Pod spustit. Pokud by se mu to nepovedlo, ať už z důvodu neexistence Docker image, nebo pádu systému při startu, tak to neovlivní aktuální běh Podů.
Pokud se mu to podaří, tak po startu zastaví jeden z předchozích Podů a začne vytvářet další. Tímto způsobem postupně vymění všechny Pody, aniž by muselo dojít k výpadku.

V našem případě jsou systémy postaveny nad Node.js. Díky tomu je start takového Podu často v řádu několika milisekund. Pokud používáte nějaké šílenosti typu Weblogic server, který startuje cca týden, tak právě díky postupné výměně Podů, nemusíte zaznamenat žádný výpadek.

V Kubernetes existuje velká škála objektů. Zde je výčet těch, se kterými sám pracuji a považuji je za ty nejzásadnější:
  • Namespace - jmenný prostor, vhodný například pro určování prostředí
  • Deployment - definuje tvorbu Podů
  • Pod - běžící Docker kontejner
  • Service - služba, sloužící na sloučení Podů pod jeden vstupní bod, může sloužit jako Load Balancer
  • ConfigMap - objekt obsahující konfigurace, nejčastěji se tato konfigurace namapuje do Podů
  • Secret - stejný jako ConfigMap s tím rozdílem, že hodnota není na první pohled viditelná a je v ukládána v base64; nejčastěji se používá na uložení hesel a dalších citlivých informací
  • Ingress - objekt určený pro externí přístup, příkladem je třeba vystavení Vaší aplikace přes nginx server s SSL; Ingress je nad objektem Service a může tedy sloužit také jako Load Balancer


Kubernetes je úžásná technologie, která tady s námi několik let jistě bude. Informace o tom, jak použít Kubernetes třeba v Azure, najdete zde. Pokud byste si chtěli Kubernetes vyzkoušet pouze lokálně, není lepší volby než přes minikube.

Krok třetí: Helm


Pokud jsme zvládli Docker a Kubernetes, tak poslední třešničkou na dortu je Helm. A i když se Vám může zdát, že Helm je technologie, která už není tak potřebná, opak je pravdou Kubernetes bez Helmu je stejné, jako jezdit v rychlém autě se zataženou ruční brzdou.

Co je to tedy Helm? Jedná se o Package Manager pro Kubernetes. Vím, tohle je asi nic neříkající věta a proto pojďme si opět ukázat, kde by se nám Helm mohl hodit.

Vraťme se k našemu projektu. Projekt je složen ze 6ti systémů, které jsou mezi sebou provázané a navíc potřebují několik věcí, jako je ono připojení k databázi, připojení k privátní Docker repozitory, vystavení několik služeb přes nginx SSL, apod. Tím nám vznikají vcelku složité předpoklady k sestavení celého projektu. Co kdybychom ale řekli, že celý náš projekt vytvoříme od nuly a to pouze jedním příkazem?

A zde právě přichází na řadu Helm. Celý náš projekt můžeme zabalit do balíčku, který nainstalujeme jako kdybychom instalovali jakýkoli jiný program.

Zde je ukázka instalace v Helmu, která provede nasazení celého prostředí jako jeden balík:
helm install repo/projekt-x --namespace dev --name projekt-x-dev -f values-dev.yaml 

Tento příkaz vytvoří namespace dev a nainstaluje Kubernetes objekty, které jsou definovány v repozitáři repo/projekt-x. Onen balík bude pojmenován jako projekt-x-dev a navíc do jednotlivých definic vloží hodnoty ze souboru values-dev.yaml.

Stejně jako v případě Docker image bychom NEMĚLI do Helm Chart ukládat citlivé informace. K tomu právě slouží možnost při instalaci připojit soubor, který obsahuje ruzná hesla a další hodnoty, kterým nastavíme celý projekt.

Poté si můžeme nechat vypsat všechny balíčky, které jsme pomocí Helmu nainstalovali:
helm ls

Pomocí Helmu můžeme celý balíček smazat a tím smazat celé prostředí. Můžeme se pomocí Helmu i vracet k různým revizím. Představte si, že nasazujete novou verzi celého vašeho projektu. V testech bylo vše v pořádku a co čert nechtěl, na produkci je problém. Není nic snazšího, než pomocí Helm rollback se vrátit k předchozí verzi:
helm rollback system-x-dev 23

Pro představu si pojďme popsat třeba Wordpress. Wordpress je všeobecně známý redakční systém a na své fungování potřebuje několik věcí: apache, php a mysql. Co kdybychom ale Wordpress pomocí Helmu nainstalovali třeba takto:
helm install --name my-release stable/wordpress
Důvod, proč jsem si zvolil zrovna ukázku pro Wordpress, není náhoda. Existuje totiž oficiální balík Wordpress Chart.

Pojďme se nyní podívat na to, jak se takový Helm Chart tvoří. První základní věcí je soubor Chart.yaml, který obsahuje základní informace o našem balíku:
apiVersion: v1
appVersion: "1.0"
description: Nas pokusny system
name: system-x
version: 0.0.1

Nejdůležitější věcí je atribut name a version. Díky tomu jsme schopni identifikovat náš balík. Další součástí je adresář templates, ve kterém si již tvoříme vlastní definice Kubernetes objektů.

V případě, že máte již balík v Kubernetes nainstalován, máte možnost změnit jeho hodnoty. A to také pouze částečně. Představte si, že máte nainstalováné prostředí dev a chcete změnit verzi Docker image pro frontend. Ideální kandidát v CD/CI:
helm upgrade --reuse-values --wait system-x-dev repo/system-x --namespace dev --set frontend.image.tag=1.0.3-dev

Závěr


Stejně jako Kubernetes, tak i Helm je technologie, která se nedá popsat v rámci jednoho článku. I když se na první pohled může zdát, že je to příliš složité, tak opak je pravdou. Sám jsem toho důkazem. Stačí úvest jeden příklad. Kubernetes a Helm jsem si osvojil během několika dní. Postupnými kroky se dopracoval až k tomu, že dnes pouze vylepšuji současný stav.
V budoucnu se zkusím více zaměřit na samotný release management, který dost ovlivňuje to, jakým způsobem budeme s Dockerem, Kubernetes a Helmem pracovat.

"Happy helming"

neděle 18. března 2018

Jak psát stabilní kód v JavaScriptu?

Pokud se rozhodnete, že v JavaScriptu napíšete větší část kódu, tak narazíte na to, že bez podpůrných nástrojů se z této cesty může stát peklo. Existuje velké množství vývojářů, kteří Vám řeknou, že JavaScript je bastl a nedá se v něm smysluplně napsat nic jiného, než pár drobností na rozhýbání webu. Opak je pravdou. V současné době je JavaScript nejuniverzálnějším jazykem na světě.

Je vcelku jedno, zda v JavaScriptu píšete aplikace typu backend, web, mobil, desktop, příkazy pro konzoli či třeba cloud funkce. Stále byste se měli snažit o to, abyste svůj kód zapsali tím nejlepším možným způsobem.

JavaScript se za posledních několik let výrazně změnil. Dostali jsme se do stavu, kdy existují dvě skupiny programátorů.

První skupinou jsou ti, kteří ignorují nové ECMAScript specifikace a JavaScript zapisují "starým způsobem". Do této skupiny často spadají lidé, kteří potřebují občas rozhýbat určitou část webu a JavaScript chápají jako jazyk, který přímo vykoná webový prohlížeč. O této skupině vývojářů se dá říci, že vlastně neumí v současném JavaScriptu programovat.

Druhou skupinou jsou vývojáři, kteří umí využít věci jako je Node.js, Babel, Typescript, apod. Kód v JavaScriptu zapisují v nových ECMAScript specifikacích a fakticky jsou schopni z tohoto jazyka často vytěžit maximum. Jedná se o naprosto jiný svět, než je tomu v případě první skupiny.

Abych Vám toto předal trochu více exaktněji, podívejte se na následující příklad, který ilustruje rozdíl mezi první a druhou skupinou:
// prvni skupina
function oldWay(options) {
    return {
        name: options.name,
        hello: function () {
            return 'Hello ' + options.name;
        }
    }
}

// druha skupina
const newWay = ({name}) => ({name, hello: () => `Hello ${name}`});

console.log(oldWay({name: 'Old way'}).hello());
console.log(newWay({name: 'New way'}).hello());

Tento kód je založen na využití arrow functions, string interpolation a destructuring assignment. Věřte, že je to jen část vlastností, které nové ECMAScript specifikace nabízí. Teď ruku na srdce, pokud je zde čtenář té první skupiny, poznal by, že ten druhý zápis ve výsledku dělá tu samou věc? Na JavaScript se dá koukat jako na dva jazyky. Na jazyk před ECMAScript 6 a jazyk s ECMAScript 6 a vyšší.

Ale pojďme zpět. Jak zajistit to, abychom v JavaScriptu byli schopni psát stabilní kód, který se nám nerozsype s novou posilou v týmu či tím, že někdo bude psát "starým" a někdo "novým" způsobem?

Airbnb JavaScript Style Guide

První věcí, kterou by každý JavaScript programátor měl začít je, že si přečte a osvojí si style guide, tedy zápis JavaScript kódu. K tomtu účelu se výborně hodí následující příručka Airbnb JavaScript Style Guide.
Dokud si toto neosvojíte, těžko se můžete považovat za seniornějšího JavaScript programátora.

Typescript / Flow

Pokud to s JavaScriptem myslíte skutečně vážně, určitě byste se měli snažit o to, abyste tento jazyk obohatili o statickou typovou kontrolu. Jelikož je JavaScript dynamicky typovaný jazyk, tak v případě, že se Vám projekt v JavaScriptu rozšíří, tak bez typové kontroly je jakýkoli refactoring roven ruské ruletě. Osobně preferuji Typescript a důvody proč, jsem sepsal v článku Proč právě Typescript.

Typescript strict mode

Součástí Typescriptu je i možnost nastavení striktního módu. Toto nastavení se jmenuje přímo "strict". Co se díky tomutu módu vše zapne, najdete v manuálu: https://www.typescriptlang.org/docs/handbook/compiler-options.html

ESLint / TSLint

Další nezbytnou součástí je ESLint (v Typescriptu TSLint). Linting, nebo-li "lustrování" kódu slouží k tomu, aby Vám nadával za to, že jste kód nezapsali zrovna tím nejlepším způsobem. Například Vám řekne, že jste napsali function, místo toho, abyste použili arrow function, že jste string zapsali ve špatných uvozovkách, že jste překročili limit počtu znaků na řádku, apod.
I když možná budete tento linter na začátku nenávidět, tak věřte, že je to dočasné. Časem totiž poznáte, že je to velice dobrý sluha. Dá se říci, že Vás naučí správně zapisovat JavaScript kód.

Prettier

Dalším skvělým pomocníkem je Prettier. Tento nástroj slouží k tomu, že za Vás automaticky formátuje kód. K čemu je to vlastně dobré?
Osobně pracuji tak, že když píšu kód, tak automaticky stále spouštím dvě základní operace nad kódem: "Format code & Optimize imports". Dělám to tak už roky a jsem přesvědčen, že by toto měl dělat každý vývojář. Každý moderní vývojový nástroj (Atom, WebStorm, Visual Studio Code, apod) má tyto dvě operace k dispozici.
Ve chvíli, kdy pracuji na projektu, kde je více lidí, tak bez automatického formátu vzniká problém. Co dokáže naprosto otrávit je, když automaticky formátujete kód jen v editoru a najednou uděláte změny i tam, kde jste vůbec nepracovali. Git Vám poté hlásí, že poslední změnu na daném řádku jste udělali Vy a přitom to není vůbec pravda.
První variantou je, že všem vývojářům přikážete, že musí používat jedno IDE a jeden styl formátování. A věřte, to je to poslední, co chcete dělat. Ne každý chce třeba psát kód v IntelliJ IDEA. Proto zde máme Prettier. Nástroj, který za nás určí pravidla a vy se jim automaticky přizpůsobíte, ať už píšete v poznámkovém bloku či třeba v Atomu.
Druhou důležitou vlastností je to, že Prettier Vám formátuje kód tak, aby správně doplnil závorky, středníky, atd, podle jasně definovaného style guide.

Integrace TSLintu a Prettier s Gitem

Nyní se pojďme podívat na to, jak využít TSLint a Prettier při práci s Gitem. Berme v potaz, že již máte projekt v Gitu. Projekt je v Typescriptu a jedná se o React aplikaci.

Nejprve do projektu přídáme závislost na tslint a tslint-react:
npm i -D tslint tslint-react

Poté do projektu přidáme soubor tslint.json:
{
  "extends": [
    "tslint:recommended",
    "tslint-react"
  ],
  "rules": {
    "max-line-length": [
      false,
      160
    ],
    "semicolon": [
      true,
      "always",
      "ignore-bound-class-methods"
    ],
    "quotemark": [
      true,
      "single",
      "jsx-double"
    ],
    "member-ordering": [
      true,
      "variables-before-functions"
    ],
    "ordered-imports": false,
    "interface-name": false,
    "object-literal-key-quotes": [
      true,
      "as-needed"
    ],
    "object-literal-sort-keys": false,
    "no-object-literal-type-assertion": false,
    "no-empty-interface": false,
    "jsx-no-multiline-js": false,
    "jsx-boolean-value": false,
    "member-access": false
  }
}

Do package.json stačí přidat následující skript:
"scripts": {
    "tslint": "tslint -c tslint.json 'src/**/*'"
}

A poté spustit:
npm run tslint
Hlásí Vám tslint chybu? Pokud ano, tak nezbýbá, než ony chyby opravit :)

Nyní pojďme přidat prettier:
npm i -D husky prettier pretty-quick
Současně s knihovnou prettier nainstalujeme knihovnu husky, která slouží k tomu, že vytvoří git hook.

Dále v projektu vytvoříme soubor .prettierrc.json:
{
  "printWidth": 160,
  "tabWidth": 4,
  "parser": "typescript",
  "singleQuote": true,
  "bracketSpacing": false,
  "trailingComma": "all",
  "arrowParens": "always"
}

Jelikož použijeme pretty-quick pro provedení automatického formátování, je třeba definovat soubor .prettierignore, ve kterém určíme adresáře a soubory, které z automatického formátovaní chceme vynechat:
.circleci/
.next/
dist/
package.json
package-lock.json

Poté, co máme základní konfiguraci hotovou, nezbývá, než obohatit náš package.json:
"scripts": {
    "tslint": "tslint -c tslint.json 'src/**/*'",
    "precommit": "pretty-quick --staged && npm run tslint"
}
A nyní stačí zkusit provést commit do gitu :)

Toto řešení je postavené na tom, že používáte Git. Před tím, než se provede samotný commit do Gitu, tak se nejprve spustí formát kódu a poté se překontroluje pomocí TSLintu. Pokud máte něco špatně, commit se neprovede. Pokud Vám nevyhovuje precommit, můžete využít i možnost prepush, tedy před tím, než se provede push do remote git repozitáře. Nicméně výsledkem je, že se Vám do společného Git repozitáře vždy dostane pouze kód, který je spravné formátovaný a zkontrolovaný pomocí linteru.

Kromě Git hooku je určitě vhodné, abyste toto provedli ještě v CI. Tedy ve vašem nástroji na continuous integration. V našem případě se jedná o CircleCI, kde pouze spustíme samotný příkaz npm run tslint a tím zajistíme, že před nasazením na server nemáme v kódu něco špatně.

Závěr

Zajistit štábní kultruru v JavaScript projektech není složitá záležitost. Celé je to pouze o tom, že čím déle budete věci jako je TSLint či Prettier ignorovat, tím víc práce v budoucnu budete mít.
Také je dobré zmínit, že nelze nekriticky spoléhat na tyto nástroje. Stále je pouze na Vás, zda kód, který napíšete je nakonec funkční. Nejsou to nástroje, které Vás například zbaví nutnosti psát unit testy.
A co vy? Používáte některé ze zmíněných nástrojů?

pátek 2. března 2018

GraphQL na reálném projektu

Pokud při vývoji backend API začnete uvažovat o náhradě RESTu za GraphQL, tak Vám gratuluji, protože jste s největší pravděpodobností zvolili správně :)

Psát o výhodách samotného GraphQL je asi zbytečné. Stačí jen nekriticky říct, že: "Konečně máme smysluplný způsob jak získávat data z backendu na frontend."

GraphQL můžete implementovat v několika jazycích. Počínaje Javascriptem a třeba Javou konče. Nicméně, pokud to s GraphQL myslíte vážně, určitě bych se raději vydal cestou javascriptu. Důvod je čistě pragmatický a to ten, že v javascriptu budete mít nejlepší podporu a i samotní autoři tento jazyk berou jako výchozí.

Reálný projekt s GraphQL

V současné době naše firma ApiTree pracuje na projektu, který vyžaduje tvorbu veřejného API a také tvorbu uživatelského portálu, který používá právě zmíněné GraphQL API.

Pro tento projekt jsme zvolili následující technologie:

  • Typescript
  • Next.js/React
  • Apollo
  • GraphQL
  • Node.js
  • Express
  • CosmosDB/MongoDB
  • Kubernetes

Tím, že na projektu pracuje více vývojářů, tak jsou rozděleni na své sféry vlivu. I přes to, že používáme jeden jazyk, tak je velice náročné nechat vývojáře stále přepínat mezi psaním backendu pomocí Mongoose a frontendu v podobě Next.js.

Pokud bychom vývoj rozdělili na backend a frontend, tak společným prvkem se stává samotné GraphQL schéma. Toto schéma potřebují znát obě strany.

Pro naše účely jsme tedy rozdělili projekt na několik systémů:

  • Backend - Express, GraphQL Apollo server, Mongoose
  • GraphQL - GraphQL schéma, GraphQL Apollo mock server
  • Frontend - Next.js / React, GraphQL Apollo client

Strana backendu a frontendu je asi zřejmá, proto se pojďme spíše podívat, proč jsme zvolili samostatný projekt pro GraphQL API.

Projekt GraphQL schéma

Když jsme přemýšleli jak nejjednodušeji napsat GraphQL schéma, skončili jsme samozřejmě u toho, že píšeme čisté schéma v souborech s příponou *.graphql. Definice tohoto schématu obsahuje vše co potřebujeme. Definuje query, mutace, nabízí i jednoduchou dokumentaci v podobě description nad jednotlivými graphql objekty a atributy.

Toto samotné schéma nic samo neumí, pouze definuje jak API bude vypadat.

Jelikož používáme Typescript, hodilo se nám, abychom z daného GraphQL schéma vygenerovali typovou definici, kterou poté použije jak backend, tak frontend. K tomuto účelu nám dobře posloužila knihovna GraphQL Code Generator. Poté jsme celý projekt vzali a vytvořili z něj NPM balík pomocí npm publish.

Nyní máme k dispozici GraphQL schéma s Typescript definicemi jak pro frontend tak pro backend.

Vedle toho jsme tento projekt využili ještě k jedné věci a tou je tvorba mock serveru. Tvorba tohoto mock serveru byla velice jednoduchá. Vzali jsme samotný soubor graphql a poslali ho do metody addMockFunctionsToSchema z knihovny graphql-tool. Pokud vezmeme samotné schéma, tak tato metoda nám nabízí výchozí mocky v podobě předem definovaného řetězce na string, number, apod. Nicméně tato volba je přepisovatelná, stejně jako implementování metody resolve. Zjednodušeně se dá říci, že napíšeme graphql schéma, pošleme do gitu a CircleCI nám zajistí jak tvorbu NPM balíčku pro frontend a backend, tak nám dále v Kubernetes vystaví mock server, který rovnou můžeme volat.

Závěr

Psát o tom, jak pomocí Apollo frameworku volat GraphQL v React komponentách je asi zbytečné, k tomu stačí jednoduchý tutoriál.

Na straně backend serveru je to stejné. Vezmeme graphql definici a jen dopíšeme resolve metody. Ve spojení s Mongoose a samotnou typovou definicí z GraphQL schématu, máte vlastně hotové kontrolery a jen se dopisuje implementace.

Práce s GraphQL není jen velice rychlá a efektivní, ale i zábavná. Když k tomu připočteme takové věci jako je start Node.js serveru během několika milisekund, tak tvorba GraphQL API vlastně vzniká v realtime čase psaním graphql schéma souboru.

A co vy? Už jste na GraphQL přešli?

úterý 20. února 2018

Nová verze Next.js 5 a Typescript


Před pár dny vyšla nová verze nejpoužívanejšího stacku pro React: Next.js 5.0. Seznam změn lze nalézt na oficiálním blogu. Jednou z klíčových vlastností je i podpora pluginů a to zejména pluginu @zeit/next-typescript.

Samotný example od Next.js bohužel neposkytuje ukázku, jak zprovoznit custom server s Typescriptem. Pokud Vás zajímá, tak jak provozovat next-typescript plugin s custom serverem, tak čtěte dál :)

Custom server a Typescript

V případě, že používáte custom server, je třeba samotnou konfiguraci obohatit o několik dalších kroků.

Začněme nejdříve přípravou skriptů v package.json:
  "scripts": {
    "prebuild": "rimraf dist/ && rimraf .next/",
    "build": "next build && tsc --module commonjs",
    "start": "NODE_ENV=production node dist/index.js",
    "dev": "nodemon server/index.ts"
  }

Dalším krokem je úprava tsconfig.json:
{
  "compileOnSave": false,
  "compilerOptions": {
    "target": "esnext",
    "module": "esnext",
    "jsx": "preserve",
    "allowJs": true,
    "moduleResolution": "node",
    "allowSyntheticDefaultImports": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "removeComments": false,
    "preserveConstEnums": true,
    "sourceMap": true,
    "skipLibCheck": true,
    "outDir": "dist",
    "baseUrl": ".",
    "typeRoots": [
      "./node_modules/@types"
    ],
    "lib": [
      "dom",
      "es2015",
      "es2016"
    ]
  },
  "include": [
    "server/**/*.ts"
  ]
}

Soubor nodemon.json:
{
  "watch": [
    "server/**/*.ts"
  ],
  "execMap": {
    "ts": "ts-node --compilerOptions '{\"module\":\"commonjs\"}'"
  }
}

Soubor next.config.js (v ukázce je i custom konfigurace webpacku):
require('dotenv').config();
const withTypescript = require('@zeit/next-typescript');
const webpack = require('webpack');

module.exports = withTypescript({
    webpack(config) {
        config.plugins = [
            ...config.plugins || [],
            new webpack.DefinePlugin({
                'process.env.BACKEND_ENDPOINT': JSON.stringify(process.env.BACKEND_ENDPOINT),
            }),
        ];
        return config;
    },
});

Aby byl projekt validní, je třeba dodržet následujcící adresářovou strukturu:

  • server/index.ts - custom node.js server
  • pages/*.tsx - jednotlivé Next.js / React stránky
  • .next/ - build samotného Next.js (viz npm run build)
  • dist/index.js - zkompilovaný custom server (viz npm run build)

Závěr


Next.js a Typescript je nyní ve skvělé symbióze. Server side renderingu zdar! :)

React a hrátky s TypeScriptem

V minulosti jsem se již několikrát zmiňoval, že používat JavaScript bez statických typů, je stejné jako jezdit na kole poslepu. Nemusí se...